오류 코드

모든 오류는 하나의 봉투(envelope)를 공유하며 안정적이고 기계가 읽을 수 있는 code를 포함합니다. (변경될 수 있는) message나 HTTP 상태만이 아니라 error.code를 기준으로 분기하세요.

{
  "error": {
    "code": "validation_failed",
    "message": "territories must be ISO 3166-1 alpha-2",
    "request_id": "req_01HQ...",
    "details": [{ "field": "territories", "issue": "invalid_format" }]
  }
}

request_id는 귀하의 X-NU-Request-Id (또는 서버가 생성한 값)를 그대로 반환합니다 — 지원 요청 시 함께 포함하세요. details는 검증 오류일 때 제공됩니다.

코드 레퍼런스

코드	HTTP	의미	일반적인 조치
`invalid_api_key`	401	키가 누락, 형식 오류, 미확인 또는 만료됨	올바른 환경에 맞는 유효한 Authorization: Bearer 키를 전송하세요
`api_key_revoked`	401	키가 폐기됨	활성 키로 교체하세요 (04)
`invalid_approval_token`	401	승인 토큰이 유효하지 않거나 만료되었거나 이미 사용됨(키 부트스트랩)	새 승인 토큰을 요청하고 한 번만 부트스트랩하세요 (04)
`missing_scope`	403	키에 필요한 스코프가 없음	스코프를 부여하세요. 스코프 표 참조 (03)
`organization_not_approved`	403	조직이 아직 승인되지 않음	승인을 기다리거나 온보딩을 완료하세요 (02)
`resource_not_found`	404	리소스가 없거나 귀하의 조직에 표시되지 않음	id와 귀하의 조직 접근 권한을 확인하세요
`validation_failed`	422	요청 본문/파라미터 검증 실패	details에 나열된 필드를 수정하세요
`rate_limit_exceeded`	429	키별 속도 제한 도달	Retry-After를 사용해 백오프하세요 (12)
`license_not_active`	403	이 재생을 허가하는 ACTIVE 계약이 없음	계약을 활성화하거나 프로덕션 API를 활성화하세요 (06)
`territory_not_allowed`	403	프로덕션 국가가 누락되었거나, 국가/오리진/IP가 계약/키에서 허용되지 않음	허용된 프로덕션 국가를 전송하세요. allowed_origins가 설정된 경우 허용된 오리진을 포함하고, allowed_ips를 확인하세요
`episode_not_licensed`	403	에피소드가 준비되지 않았거나, 준비된 비디오 에셋이 없거나, 라이선스된 에셋 집합에 포함되지 않음	준비된 비디오 에셋에 라이선스를 부여하거나 적용 대상인 준비된 에피소드를 사용하세요
`duplicate_event_id`	409	event_id가 이미 허용됨(멱등 무연산)	성공으로 처리하세요. 동일한 id로 재시도하지 마세요
`invalid_playback_session`	400	알 수 없거나 유효하지 않은 재생 세션	재생 API가 반환한 playback_session_id를 사용하세요
`playback_concurrency_limit`	429	이 시청자에 대한 계약/타이틀의 동시 활성 세션이 너무 많음	추가 발급 전에 기존 세션을 폐기하거나 완료/만료되도록 두세요
`settlement_not_disputable`	409	정산이 이의 제기 가능 상태가 아님	이의 제기 가능 상태일 때만 제기하세요 (09)
`conflict`	409	리소스가 이미 존재하거나, 동시/진행 중 요청이 있음(예: 재생 토큰 또는 라이선스 요청 멱등성)	멱등 요청을 재시도하거나 기존 리소스를 대사하세요
`internal_error`	500	예기치 않은 서버 오류	백오프를 적용해 재시도하세요. 지속되면 request_id와 함께 지원팀에 문의하세요

처리 지침

401 — 인증을 수정하세요. 무작정 재시도하지 마세요.
403 — 인가 문제(스코프, 조직 또는 권리)입니다. 기반 권한이 변경되기 전까지는 재시도가 도움이 되지 않습니다.
404 — id와 조직 표시 여부를 확인하세요.
422 — details[]를 살펴보고 요청을 수정하세요.
409 — 상황에 따라 다릅니다: duplicate_event_id는 이벤트가 이미 허용되었음을 의미하며(무해하므로 성공으로 처리), settlement_not_disputable는 현재 해당 작업이 허용되지 않음을 의미하고, conflict는 리소스가 이미 존재하거나 동시/진행 중 요청이 점유하고 있음을 의미합니다(예: 재생 토큰 또는 라이선스 요청 멱등성) — 멱등 호출을 재시도하거나 기존 리소스를 대사하세요.
429 — Retry-After를 준수하세요. 속도 제한를 참조하세요.
5xx — 멱등 호출을 지수 백오프로 재시도하세요.

데이터베이스 제약 매핑

알려진 데이터베이스 오류는 일반적인 500 대신 깔끔한 4xx 응답으로 매핑됩니다(예: 동시에 삭제된 행에 대한 read-then-write 경합):

DB 조건	HTTP	error.code
쓰기 시 행을 찾을 수 없음 (P2025)	404	`resource_not_found`
고유 제약 위반 (P2002)	409	`conflict`
외래 키 제약 위반 (P2003)	422	`validation_failed`