错误处理 - 算秩

当 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`	存在时，表示建议的重试前等待时间。

检查顺序

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

错误类型与建议操作

HTTP	error.type	error.code	含义	建议操作
400、422、其它 4xx	invalid_request_error	invalid_request	请求正文或参数无效	修正请求，不要立即使用相同的负载重试
429	rate_limit_error	rate_limit_exceeded	后端对此请求进行了限流	等待后重试；存在时遵循 retry_after_sec
429	RATE_LIMIT_EXCEEDED	rate_limit_exceeded 或 token_rate_limit_exceeded	达到网关配额或令牌速率限制	等待后重试；降低并发或请求速率
401	MODEL_PROXY	Unauthorized	身份验证失败	核实 API 密钥；在修正凭据前不要重试
402	BILLING_DENIED	billing_denied	超出账户配额或消费限额	充值、升级或提升配额；在解决计费问题前重试不会成功
500	BILLING_ERROR	billing_error	临时性计费系统问题	稍后重试
500、502、503	service_unavailable	service_unavailable	临时性服务问题	使用退避策略重试
499	client_aborted	通常无	客户端在响应完成前断开了连接	通常无需操作
400	unsupported_protocol	unsupported_protocol	不支持所请求的协议	切换到受支持的协议或接入点
400	PROXY_ERROR	通常无	请求无法完成	短暂重试可能有帮助；上报时请附上 traceId

通用建议

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