오류와 재시도

오류 응답

JSON API 실패는 다음 엔벌로프를 사용합니다.

{
  "error": {
    "code": "entity_not_found",
    "message": "Catalog entity not found",
    "requestId": "request-id-when-available"
  }
}

HTTP 상태와 안정된 code로 분기하세요. message는 개발자용 표시나 로그에 쓰며, 더 구체적인 문구로 바뀔 수 있습니다. requestId는 선택이며 서비스 장애를 보고할 때 유용합니다.

실제 예:

GET /api/v1/songs/{id}

아직 보내지 않음

상태 안내

상태	의미	클라이언트 대응
`400`	쿼리, 라우트 값, JSON, 배치 ID가 잘못됨	요청을 고쳐 다시 보낸다.
`401`	세션이 필요함	로그인하고 브라우저 자격 증명을 보낸다.
`403`	출처, 인증, 계정, 권한 확인 실패	요청 맥락을 바로잡거나 필요한 사용자 조치를 보여 준다.
`404`	서버, 리소스, 엔티티, 뷰, 관계, 파일을 찾지 못함	카탈로그를 새로 고치거나 없는 항목을 뺀다.
`409`	버전, 멱등성, 상태 충돌	리소스를 다시 읽고 최신 버전에 변경을 적용한다.
`413` / `415`	요청이 너무 크거나 지원하지 않는 미디어 타입	본문을 줄이거나 선언된 콘텐츠 타입을 쓴다.
`422`	본문 필드 검증 실패	응답이 가리킨 필드를 고친다.
`429`	속도 제한 또는 할당량 도달	`Retry-After`가 있으면 따르고 백오프한다.
`500`	워커의 예기치 않은 실패	멱등한 읽기를 백오프하며 재시도한다.
`502`	상위 또는 프로바이더 프로젝션 실패	읽기를 백오프하며 재시도하고 `X-Request-Id`를 보관한다.
`503`	데이터베이스, 카탈로그, ID, 스토리지를 쓸 수 없음	안전한 읽기를 백오프하며 재시도한다.

알 수 없는 오류 코드는 내용을 알 수 없는 실패로 다룹니다. 로그에는 남기고, 사용자에게 보이는 동작은 상태 분류로 정하세요.

재시도 정책

GET과 HEAD는 네트워크 장애, 408, 429, 일시적인 5xx 뒤에 안전하게 재시도할 수 있습니다. 지터를 넣은 지수 백오프를 쓰고, Retry-After를 따르며, 시도 횟수에 상한을 두세요. 일시적인 실패 뒤에는 현재 별칭을 다시 읽으세요. 재시도가 성공할 무렵 현재 카탈로그가 바뀌었을 수 있습니다.

변경 요청은 작업별 규칙이 필요합니다. 엔드포인트가 멱등성을 정의하거나 작업을 반복해도 안전할 때만 재시도하세요. 업로드 예약에는 Idempotency-Key가 필요하며, 같은 키를 다른 메타데이터로 재사용하면 409 idempotency_conflict가 반환됩니다.

흔한 카탈로그 실패

route_not_found: 최상위 경로가 공개 API 라우트가 아닙니다.
server_not_found: server 쿼리 값이 활성 상태가 아닙니다.
resource_not_found: 선택한 카탈로그 매니페스트에 리소스가 없습니다.
entity_not_found: 리소스는 있지만 요청한 ID가 없습니다.
view_not_found 또는 relation_not_found: 매니페스트에 요청한 뷰나 관계가 정의되어 있지 않습니다.
release_not_found: 고급 명시적 요청이 쓸 수 없는 릴리스 ID를 사용했습니다.

직접 별칭은 현재 데이터를 쓰며 릴리스 ID가 필요 없습니다. 빌드에서 과거 릴리스를 고정해야 하면 서버 단위 고급 계약을 참고하세요.