错误代码

每个错误都使用统一封装并含稳定的机器可读 code。请按 error.code 分支，而不是仅依赖可变的 message 或 HTTP 状态。

{
  "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批准令牌无效、过期或已用于 bootstrap请求新批准令牌并仅 bootstrap 一次 (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_allowed403缺少 Production country，或协议/密钥不允许 country、origin 或 IP发送允许的 Production country；配置时包含允许 origin，并检查 allowed_ips
episode_not_licensed403剧集未就绪、无就绪视频资产或不在授权资产集合授权就绪视频资产或使用符合条件的就绪剧集
duplicate_event_id409event_id 已接受；幂等空操作视为成功；不要改用其他 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 — 使用指数退避重试幂等调用。

数据库约束映射

已知数据库错误映射为清晰的 4xx 响应，而非通用 500，包括针对并发删除行的先读后写竞争：

数据库条件HTTPerror.code
写入时找不到行（P2025）404resource_not_found
唯一约束冲突（P2002）409conflict
外键约束冲突（P2003）422validation_failed