错误码

宁享Token API 使用标准 HTTP 状态码和结构化错误响应。本表列出所有可能的错误码及排查建议。

错误响应格式

OpenAI 兼容入口（/v1/chat/completions、/v1/video/generations 等）使用单层四键 error 对象：

json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "type": "invalid_request_error",
    "param": ""
  }
}

字段	类型	说明
`error.code`	string	业务错误码，见下方表
`error.message`	string	人类可读的错误描述
`error.type`	string	错误类别，由 HTTP 状态码推导（见「错误类型分类」）
`error.param`	string	出错的参数名；无参数时为 `""`（不会为 `null`）

Anthropic 协议入口（/v1/messages*）使用三键形态，request_id 仅此入口在响应体内返回：

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API key provided."
  },
  "request_id": "req_abc123"
}

OpenAI 兼容错误码

错误码	HTTP	含义	排查建议
`invalid_api_key`	401	API Key 无效	检查 Key 是否正确、是否过期
`invalid_request`	400	请求参数错误	检查请求体 JSON 格式、必填字段
`insufficient_quota`	429	余额不足	充值后重试

说明：error.type 的取值（invalid_request_error / rate_limit_error / server_error / service_unavailable_error）不是 error.code；invalid_model 仅在可灵视频任务面产生。上下文超限请见下方「平台扩展错误码」中的 model_context_limit_exceeded。

平台扩展错误码（NX_api_error）

平台在 OpenAI 兼容错误之外，以下列结构化错误码反馈网关侧问题（error.type 取 OpenAI 官方观测集内的取值，按 HTTP 状态码推导，例如 invalid_request_error / rate_limit_error / server_error；不使用 NX_api_error 等官方不存在的取值）：

错误码	典型场景	排查建议
`sensitive_words_detected`	请求内容命中敏感词（400）	修改请求内容；这是客户端违规而非服务故障
`model_context_limit_exceeded`	输入/输出超过模型上下文上限（400，请求前置拦截）	缩减 messages 或 max_tokens，或换长上下文模型（kimi-k3 / glm-5.3 / gemini-3.5）
`model_price_error`	模型未配置价格（可能被拒）	联系运营补配价；临时可换同系其他模型
`model_not_found`	模型不存在或未对你的分组开放	核对模型名拼写；确认分组已开放该模型
`insufficient_user_quota`	钱包余额不足	控制台充值后重试
`pre_consume_token_quota_failed`	预扣费失败（并发竞态）	重试一次；持续出现联系客服
`count_token_failed`	token 计数失败	检查 messages 格式（含 multimodal content 结构）
`bad_request_body`	请求体不是合法 JSON	校验请求体序列化
`access_denied`	无权访问该模型/分组	检查 Key 的分组权限
`channel:no_available_key`	服务暂不可用	稍后重试（自动恢复）；持续出现联系客服
`channel:response_time_exceeded`	上游响应超时	重试；长任务建议走异步接口（视频类）
`do_request_failed`	服务暂时不可用	平台自动重试与恢复
`empty_response`	上游返回空响应	重试；带 request_id 反馈客服

错误信息安全：全部 65 种适配器的上游报错经统一模板收敛后才返回——上游密钥、内部地址等敏感信息不会泄露给客户端。 | model_overloaded | 503 | 模型过载 | 稍后重试或切换其他模型 | | server_error | 500 | 服务端错误 | 稍后重试；持续失败请联系客服 | | timeout | 504 | 请求超时 | 检查 prompt 长度，减少 max_tokens | | api_error | 500 | 通用 API 错误 | 稍后重试 |

宁享Token 特有错误码

错误码	HTTP	含义	排查建议
`asset_not_found`	404	素材不存在	检查素材 ID 或 URL 是否正确
`asset_too_large`	400	素材文件过大	压缩后重试，图片 <2MB，音频 <20MB
`asset_format_unsupported`	400	素材格式不支持	转换为支持的格式（JPG/PNG/MP3/WAV）
`task_not_found`	404	任务不存在	检查 task_id 是否正确
`task_failed`	500	任务执行失败	是否计费按上游官方返回的计费信息核算（见下「任务失败会扣费吗」）；可重新创建
`task_cancelled`	400	任务已取消	任务被主动取消
`video_duration_invalid`	400	视频时长不合法	检查 duration 是否在模型支持范围内
`video_resolution_invalid`	400	分辨率不合法	检查 resolution 是否在模型支持范围内
`tts_voice_not_found`	400	音色不存在	检查 voice 参数是否正确
`tts_character_limit`	400	TTS 字符数超限	单次请求不超过 1000 字符
`asr_duration_limit`	400	ASR 音频时长超限	单次请求不超过 60 秒
`client_key_revoked`	401	API Key 已被吊销	在控制台重新创建 Key
`client_key_disabled`	403	API Key 已禁用	在控制台启用 Key
`ip_not_allowed`	403	IP 白名单限制	在控制台添加当前 IP
`billing_account_not_found`	403	账户未关联计费	联系客服关联账户
`concurrent_limit_exceeded`	429	并发数超限	降低并发或联系客服提升配额
`model_not_authorized`	403	无权使用该模型	检查账户是否开通该模型权限

错误类型分类

`error.type`	说明	典型错误码
`invalid_request_error`	请求/参数/鉴权/权限类错误（HTTP 400 / 401 / 403 / 404）	`invalid_api_key` / `model_not_authorized` / `ip_not_allowed` / `context_length_exceeded`
`rate_limit_error`	速率限制（HTTP 429）	`rate_limit_exceeded` / `concurrent_limit_exceeded` / `insufficient_quota`
`service_unavailable_error`	服务不可用（HTTP 503）	`channel:no_available_key` / `model_overloaded`
`server_error`	服务端错误（其余 5xx，含 500）	`server_error` / `do_request_failed`

error.type 由 HTTP 状态码推导，取值限于 OpenAI 官方观测集；上游厂商自有的 type 取值不会原样透出，客户请以 error.code 做精确分流。

重试建议

HTTP 状态码	是否可重试	重试策略
400	❌	不重试，修正请求参数
401	❌	不重试，检查 API Key
403	❌	不重试，检查权限
404	❌	不重试，检查资源 ID
429	✅	指数退避，间隔 1s/2s/4s/8s
500	✅	指数退避，最多重试 3 次
503	✅	指数退避，最多重试 3 次
504	✅	减小请求规模后重试

常见问题

如何获取 request_id？

/v1/messages*（Anthropic 协议入口）的错误响应体 request_id 字段；其余入口从响应头 X-Request-Id（X-Oneapi-Request-Id）获取 —— OpenAI 兼容面的错误体内不含 request_id。

429 后多久可以重试？

等待 Retry-After 响应头指定的秒数，或使用指数退避。

任务失败会扣费吗？

按上游厂商官方返回的计费信息核算，与官方口径一致：

官方未计费（返回的计费量为 0）→ 平台不计费，预扣额度自动退还；
官方已计费（计费量大于 0）→ 维持计费（该次生成的算力已被上游消耗）；
上游未返回计费信息 → 保守维持计费并标记待人工复核，核实后如属官方未计费会补退。

也就是说：「任务失败」本身不等于「不计费」，判据是厂商的计费结果。

错误码 ​

错误响应格式 ​

OpenAI 兼容错误码 ​

平台扩展错误码（NX_api_error） ​

宁享Token 特有错误码 ​

错误类型分类 ​

重试建议 ​

常见问题 ​

如何获取 request_id？ ​

429 后多久可以重试？ ​

任务失败会扣费吗？ ​

相关文档 ​

错误码