错误处理 - 算秩

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

错误响应格式

失败的请求会返回如下正文：

{
  "error": {
    "msg": "parameter check failed, temperature range is [0, 2.0]",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "parameter check failed, temperature range is [0, 2.0] (request_id: 8071e4c1-a8ce-4ab8-a010-8d9282311f9d)",
    "traceId": "1fdc54880fe9fc770e1e08fb0876f52a",
    "request_id": "8071e4c1-a8ce-4ab8-a010-8d9282311f9d",
    "retry_after_sec": 30
  }
}

字段	说明
`type`	错误类别，是判断处理方式的主要依据。
`code`	如果存在，会提供更具体的错误码（某些网关错误可能没有该字段）。
`message` / `msg`	错误说明。其中 `message` 通常包含 `request_id`，`msg` 提供简短错误信息。
`request_id`	平台生成的请求 ID，优先用于技术支持排障。
`traceId`	链路追踪 ID，与 `request_id` 是不同字段。
`retry_after_sec`	存在时，表示建议的重试前等待时间。

部分错误还会返回 param，用于标识相关请求字段；限流等可重试错误还可能返回 retry_after_sec，表示建议的重试前等待时间。

错误响应会返回用于排查的 request_id。该 ID 通常会出现在 error.message、error.request_id 以及响应 Header 的 request-id / x-request-id 中。联系技术支持时，请优先提供 request_id，并同时保留 traceId、请求时间、模型 ID 和接口路径。

检查顺序

HTTP 状态码：先判断问题的大类（4xx 表示客户端问题，5xx 表示服务端问题）。
error.type：再根据错误类型决定处理方式。
error.code：如果存在，可进一步缩小原因范围。
request_id / traceId：如果问题需要上报，请记录请求 ID、链路追踪 ID、请求时间、模型 ID 和接口路径。
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	通常无	请求无法完成	短暂重试可能有帮助；上报时请附上 request ID 和 `traceId`

通用建议

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