오류 코드

모든 오류는 안정적인 기계 판독 code를 포함한 하나의 봉투를 사용합니다. 변경될 수 있는 message나 HTTP 상태만이 아니라 error.code로 분기하세요.

{
  "error": {
    "code": "validation_failed",
    "message": "요청 검증에 실패했습니다.",
    "request_id": "req_01HQ...",
    "details": [
      {
        "field": "territories",
        "issue": "zod_invalid_format",
        "message": "값의 형식이 올바르지 않습니다."
      }
    ]
  }
}

request_id는 귀하의 X-NU-Request-Id 또는 서버 생성 값을 반환합니다. 지원 요청에 포함하세요. 검증 오류에는 details가 제공됩니다.

코드 레퍼런스

코드	HTTP	의미	일반적인 조치
`invalid_api_key`	401	키 누락, 형식 오류, 알 수 없음 또는 만료	올바른 환경의 유효한 Authorization: Bearer 키를 보내세요
`api_key_revoked`	401	키가 폐기됨	활성 키로 교체하세요 (04)
`invalid_approval_token`	401	승인 토큰이 유효하지 않거나 만료되었거나 bootstrap에 이미 사용됨	새 승인 토큰을 요청하고 한 번만 bootstrap하세요 (04)
`invalid_application_token`	401	신청 참조 또는 상태 토큰이 잘못되었거나 만료됨	초기 신청 응답의 1회 표시 상태 자격증명을 사용하세요
`missing_scope`	403	키에 필수 스코프가 없음	스코프를 부여하고 스코프 표를 참고하세요 (03)
`production_key_required`	403	Sandbox 키로 Production 전용 엔드포인트 호출	nsp_live_ 키로 정산 요청을 다시 보내세요
`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 계약이 없음	계약을 활성화하거나 Production API를 활성화하세요 (06)
`territory_not_allowed`	403	Production country 누락 또는 country, origin, IP가 계약·키에서 허용되지 않음	허용된 Production country를 보내고 설정 시 허용 origin을 포함하며 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	리소스가 이미 존재하거나 동시·처리 중 요청이 작업을 점유함	멱등 요청을 재시도하거나 기존 리소스를 대사하세요
`service_unavailable`	503	필수 서비스를 일시적으로 사용할 수 없습니다.	멱등 호출을 지수 백오프로 재시도하세요.
`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`