错误码参考

当请求发生错误时，API 返回统一的错误体：

{
  "error": {
    "code": "402",
    "type": "insufficient_balance",
    "message": "余额不足，请充值",
    "request_id": "3f2a1c9d8e7b4a6f"
  }
}

注意 code 与 type 的含义

• error.code 是 HTTP 状态码的字符串形式（如 "402"、"429"），不是语义名。
• error.type 才是语义错误名（如 insufficient_balance）。
• request_id 与响应头 X-RealApi-RequestId 一致，报障时请提供它，可据此定位到具体那一笔调用。
• 上游透传的错误，code 可能是上游返回的原始状态码，type 为 provider_api_error。
• Anthropic 端点（/api/anthropic/...）返回 Anthropic 自己的错误体格式，语义相同。

平台侧错误

HTTP 状态码	error.type	说明
400	invalid_params	请求参数无效；模型不支持图片/视频输入；上下文超长
402	insufficient_balance	账户余额不足，充值后重试
402	key_credit_exhausted	该 API Key 的额度上限已用尽（账户余额可能仍充足）
403	access_denied	未提供 API Key，或 Key 无效 / 已暂停 / 已删除
404	invalid_model	模型 ID 不存在
404	model_not_available	模型存在但当前不可用
404	model_not_supported	该模型不支持你调用的这个 API（如用 /responses 调只支持 /chat/completions 的模型）
413	request_body_too_large	请求体超过 32 MB（多模态请压缩图片或改用图片 URL）
429	rate_limit	超过该 Key 的 RPM 上限，或超大请求（> 8 MB）并发额度已满；响应带 Retry-After: 5，可重试
500	internal_server_error	平台内部错误
502	no_provider_available	该模型当前没有可用渠道（全部渠道不可用或不满足约束）

上游相关错误

HTTP 状态码	error.type	说明
422	provider_unprocessable_entity_error	上游拒绝了请求内容
429	rate_limited	上游模型服务方限流
500	provider_api_error	上游 API 返回错误（code 可能是上游原始状态码）
500	provider_error	上游服务错误
520	provider_internal_server_error	与上游通信故障
524	provider_internal_server_error	上游超时

排查建议

错误	排查方向
access_denied	检查 Key 是否复制完整、是否已在 Portal 暂停或删除
insufficient_balance	登录 Portal 查看余额并充值；建议开启低余额提醒，见按量付费
key_credit_exhausted	该 Key 设了额度上限且已用尽，联系平台支持调整或换用其他 Key
rate_limit	降低请求频率；若是大请求（> 8 MB）并发导致，按 Retry-After 退避重试，或压缩请求体
invalid_model / model_not_available	用 GET /api/v1/models 确认模型 ID 与可用状态
model_not_supported	换用该模型支持的协议端点
request_body_too_large	压缩图片（转 JPEG / 降分辨率，单图建议 5 MB 内）或改用图片 URL，不要整段 base64 塞进请求
no_provider_available	该模型暂无可用渠道，稍后重试或换用同类模型
provider_*	上游模型服务方的问题，可稍后重试；持续出现请带 request_id 联系平台支持

健康检查

GET /health

无需认证，用于检查 Gateway 服务状态。

{
  "status": "UP"
}