공통 규칙

모든 동작에 같은 오류 형식, 커서, 재시도, 버전 규칙을 적용합니다.

오류

오류는 HTTP 상태 코드와 함께 아래 형식으로 돌아옵니다. 분기는 code로 하고, 문의할 때는 request_id를 전달하세요.

오류 응답

{
  "error": {
    "code": "FORBIDDEN_SPACE",
    "message": "이 공간을 볼 권한이 없습니다.",
    "request_id": "req_demo"
  }
}

상태	code	의미
400	`INVALID_REQUEST`	입력이 형식이나 범위에 맞지 않습니다.
400	`INVALID_CURSOR`	알 수 없거나 만료된 커서입니다. 처음부터 다시 읽습니다.
401	`UNAUTHENTICATED`	키가 없거나 유효하지 않습니다.
403	`FORBIDDEN_SPACE`	지정한 공간을 볼 권한이 없습니다. 내용은 반환하지 않습니다.
404	`NOT_FOUND`	대상이나 경로가 없습니다.
409	`DECISION_CONFLICT`	이미 다른 결정이 기록된 기억입니다.
409	`IDEMPOTENCY_KEY_REUSED`	같은 Idempotency-Key로 다른 내용을 보냈습니다.

목록 응답의 next_cursor를 다음 요청의 cursor로 보냅니다. null이면 마지막 페이지입니다. 커서는 해석하지 말고 그대로 전달하세요.

변경 동기화의 커서는 저장해 두었다가 다음 동기화에서 이어 읽습니다. 커서 보존 기간은 정해지지 않았습니다.

상태를 바꾸는 사람 확정은 Idempotency-Key 헤더가 필요합니다. 네트워크 오류로 결과를 모르면 같은 키로 다시 보내세요. 첫 결과가 replayed: true로 돌아옵니다. 같은 키로 다른 내용을 보내면 409입니다.

재시도할 상태 코드와 간격, 요청 한도는 Backend 계약 확정 후 이곳에 적습니다.

경로의 /v1은 API 버전, health의 contract_version은 명세 버전입니다. 필드 추가처럼 호환되는 변경은 같은 경로 버전 안에서 이뤄지고, 호환되지 않는 변경은 새 경로 버전과 함께 안내합니다.