第 3/4 节课 · 8 分钟
请求失败时
根据错误代码和状态码分别处理,只重试那些稍后可能成功的错误。
Phaseo 的所有错误在每个端点上都使用相同的 JSON 响应体。error 对象的结构就是兼容 OpenAI 的 SDK 已经能读取的格式:
{
"error": {
"code": "insufficient_funds",
"message": "...",
"type": "insufficient_quota",
"param": null
},
"generation_id": "G-...",
"status_code": 402
}
根据 error.code 和 HTTP 状态码分别处理,永远不要依据消息文本。始终记录 generation_id。
| 状态码 | 常见代码 | 怎么做 |
|---|---|---|
400 | validation_error、model_required | 修正请求。error.param 会指出是哪个字段。 |
401 | unauthorised | 检查密钥和 Authorization 请求头。 |
402 | insufficient_funds | 充值额度,或使用 phaseo/free。 |
403 | guardrail_blocked | 修改请求或护栏。 |
404 | not_found | 检查路径和 ID。 |
410 | model_retired | 切换到 replacement_model。 |
429 | rate_limit_exceeded、key_limit_exceeded | 等待 Retry-After 后重试。 |
5xx | upstream_error、gateway_error | 退避重试。 |
除 429 外,不要原样重试 4xx 错误:它们还会失败。对于 429,等待 Retry-After(秒数或 HTTP 日期),或使用带抖动的指数退避。没有 Retry-After 的 key_limit_exceeded 不会自行重置,所以不要重试它。只有在重复调用是安全的情况下才重试 5xx,并设置尝试次数上限和总截止时间。
检验你的理解
你的请求返回 401,代码为 unauthorised。你的代码应该怎么做?
学以致用
一个批处理脚本在循环中发送 500 个请求。进行到一半时,响应开始返回 429,并带有 Retry-After: 20 请求头。你要改什么?
显示答案隐藏答案
让脚本遵守 Retry-After:重试前暂停大约 20 秒;如果没有这个请求头,就退回到带抖动的指数退避。同时检查 error.code:rate_limit_exceeded 会重置,但没有 Retry-After 的 key_limit_exceeded 不会,重试它毫无意义。
要点
根据
error.code 和状态码分别处理,修正 4xx 错误,只对 429 和可安全重试的 5xx 错误做退避重试。相关链接
进度保存在此浏览器中。
最后核对于 2026年11月17日