第 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。

状态码常见代码怎么做
400validation_error、model_required修正请求。error.param 会指出是哪个字段。
401unauthorised检查密钥和 Authorization 请求头。
402insufficient_funds充值额度,或使用 phaseo/free。
403guardrail_blocked修改请求或护栏。
404not_found检查路径和 ID。
410model_retired切换到 replacement_model。
429rate_limit_exceeded、key_limit_exceeded等待 Retry-After 后重试。
5xxupstream_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日