エラーコード

すべてのエラーは安定した機械可読codeを含む1つのエンベロープを使います。変更可能な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_key401キー不足、形式不正、不明、または期限切れ正しい環境の有効なAuthorization: Bearerキーを送信
api_key_revoked401キーが失効済みアクティブキーへ交換 (04)
invalid_approval_token401承認トークンが無効、期限切れ、またはブートストラップで使用済み新しい承認トークンを要求し一度だけブートストラップ (04)
invalid_application_token401申請参照または状態トークンが誤り・期限切れ初回申請レスポンスの一度表示される状態認証情報を使用
missing_scope403キーに必要なスコープがないスコープを付与し表を参照 (03)
production_key_required403SandboxキーでProduction専用エンドポイントを呼び出したnsp_live_キーで精算リクエストを再送
organization_not_approved403組織が未承認承認を待つかオンボーディングを完了 (02)
resource_not_found404リソースがない、または組織に表示されないIDと組織のアクセス権を確認
validation_failed422本文・パラメータ検証失敗details記載のフィールドを修正
rate_limit_exceeded429キー単位レート制限到達Retry-Afterに従いバックオフ (12)
license_not_active403この再生を認可するACTIVE契約がない契約を有効化するかProduction APIを有効にする (06)
territory_not_allowed403Productionのcountry不足、またはcountry・origin・IPが契約やキーで未許可許可されたProduction countryを送り、設定時は許可originを含めallowed_ipsを確認
episode_not_licensed403エピソード未準備、準備済み動画なし、またはライセンス対象外準備済み動画をライセンスするか対象エピソードを使用
duplicate_event_id409event_idは受理済み（冪等no-op）成功として扱い別IDで再試行しない
invalid_playback_session400不明・無効な再生セッション再生APIが返したplayback_session_idを使用
playback_concurrency_limit429視聴者の契約・タイトルにアクティブセッションが多すぎる既存セッションを失効するか完了・期限切れ後に発行
settlement_not_disputable409精算が異議申立て可能な状態でない許可された状態でのみ異議申立て (09)
conflict409リソース既存、または同時・処理中リクエストが操作を保持冪等リクエストを再試行するか既存リソースを照合
service_unavailable503必要なサービスは一時的に利用できません。冪等呼び出しを指数バックオフで再試行してください。
internal_error500予期しないサーバーエラーバックオフで再試行し、継続する場合request_id付きでサポートへ連絡

処理ガイダンス

  • 401 — 認証を修正し、むやみに再試行しないでください。
  • 403 — スコープ、組織、権利の認可問題です。基礎権限が変わるまで再試行は有効ではありません。
  • 404 — IDと組織の表示可否を確認してください。
  • 422 — details[]を確認しリクエストを修正してください。
  • 409 — コードによります。duplicate_event_idはイベント受理済みなので成功扱い、settlement_not_disputableは現在操作不可、conflictはリソース既存または同時リクエスト処理中です。必要に応じ冪等呼び出しを再試行するか既存リソースを照合します。
  • 429 — Retry-Afterを守ってください。レート制限を参照。
  • 5xx — 冪等呼び出しを指数バックオフで再試行してください。

データベース制約のマッピング

既知のDBエラーは一般的な500ではなく明確な4xxへマッピングされ、同時削除行へのread-then-write競合も含みます:

DB条件HTTPerror.code
書き込み時に行がない（P2025）404resource_not_found
一意制約違反（P2002）409conflict
外部キー制約違反（P2003）422validation_failed