跳转到主要内容

​
错误处理

当 API 调用失败时，响应通常会包含 HTTP 状态码和 JSON 错误正文。请结合这两部分信息判断：是需要修正请求，还是等待后重试。

​
错误响应格式

失败的请求会返回如下正文： 
{
  "error": {
    "status": false,
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Invalid parameter: temperature must be between 0 and 2.",
    "msg": "Invalid parameter: temperature must be between 0 and 2.",
    "param": "temperature",
    "traceId": "abc123",
    "retry_after_sec": 30
  }
}
字段说明
type错误类别，是判断处理方式的主要依据
code如果存在，会提供更具体的错误码（某些网关错误可能没有该字段）
message / msg面向用户的错误说明；两个字段中可能只返回其中一个
param与错误相关的请求字段（适用时）
traceId排查问题时请提供此字段
retry_after_sec存在时，表示建议的重试前等待时间

​
首先检查什么

  1. HTTP 状态码：先判断问题的大类（4xx 表示客户端问题，5xx 表示服务端问题）。
  2. error.type：再根据错误类型决定处理方式（见下表）。
  3. error.code：如果存在，可进一步缩小原因范围。
  4. retry_after_sec：如果返回了该字段，重试前请至少等待对应秒数。

​
错误类型与建议操作

error.typeHTTPerror.code含义应对方法
invalid_request_error400、422、其它 4xxinvalid_request请求正文或参数无效修正请求；不要立即使用相同的负载重试
rate_limit_error429rate_limit_exceeded后端对此请求进行了限流等待后重试；存在时遵循 retry_after_sec
RATE_LIMIT_EXCEEDED429rate_limit_exceeded 或 token_rate_limit_exceeded达到网关配额或令牌速率限制等待后重试；降低并发或请求速率
MODEL_PROXY401Unauthorized身份验证失败核实 API 密钥；在修正凭据前不要重试
BILLING_DENIED402billing_denied超出账户配额或消费限额充值、升级或提升配额；在解决计费问题前重试不会成功
BILLING_ERROR500billing_error临时性计费系统问题稍后重试
service_unavailable500、502、503service_unavailable临时性服务问题使用退避策略重试
client_aborted499（通常无）客户端在响应完成前断开了连接通常无需操作
unsupported_protocol400unsupported_protocol不支持所请求的协议切换到受支持的协议或接入点
PROXY_ERROR400（通常无）请求无法完成短暂重试可能有帮助；上报时请附上 traceId

​
通用重试指南

  • 不要重试： 对于身份验证失败（401）、计费拒绝（402）和无效请求（400 / 422），请先解决根本问题。
  • 使用退避策略重试： 对于速率限制（429）和服务端错误（5xx），建议采用退避重试；如果响应中包含 retry_after_sec，请优先遵循该值。
  • 记录 traceId： 如果错误持续出现，或您无法自行定位问题，请记录错误响应中的 traceId 并联系我们以便进一步排查。