请求排查

AI API 错误：401、429、5xx 和超时

区分 OpenAI、Claude 和 Gemini API 的身份认证、配额、请求限速与暂时失败。决定重试前先使用错误详情。

作者：IsAnythingDown已核对 2026-10-06阅读 Markdown ↗

简要回答

API 错误本身不能确认提供方故障。请查看提供方的错误正文和请求 ID，再核对对应状态组件。认证和计费问题需要调整配置；临时失败可能适合有限重试。

使用此表选择首次检查。确切含义和措施取决于提供方、端点和错误正文。

检查 error.code，而不只看 HTTP 429。OpenAI 区分请求频率限制、积分耗尽和组织／项目限制。计费与配额失败不会通过重复重试解决。对于暂时请求限速或过载，应遵循已提供的 Retry-After 并限制重试。

API 组件请使用 OpenAI API 条目。ChatGPT 应用条目不能确认 API 请求结果或具体 GPT 模型健康。

Claude 文档将 529 定义为过载、401 为身份认证失败、403 为权限失败。429 可能表示请求限速或支出上限。使用等级支出上限对应的 429 没有 Retry-After 响应头，会持续失败直至访问恢复。选择重试策略前应读取完整错误。

Claude 文档说明流式响应可能在 HTTP 200 之后发生错误。应检查流是否完成及错误事件；仅收到响应头不能确认生成成功。

Google 对暂时失败建议采用带随机延迟的有界指数退避。也应检查 API 版本、模型及支持的参数。请查看开发者 API 自己的报告；Gemini 应用事件流不覆盖 Gemini API 或 AI Studio 请求。

作为应用设计选择，应同时设置最大尝试次数和总时间预算。计入 SDK 已执行的重试。对于提供方认定为临时性的错误，采用带随机抖动的指数退避延迟，并遵守适用的重试标头。

重放中断请求前，请核对它是否已经产生输出、费用或下游操作。重试模型请求与重复 Agent 的工具操作是不同决策。保留请求 ID 以便排查，并在允许的预算耗尽后停止自动重试。

请使用针对请求所返回错误的专用指南。这些页面解释请求失败，不监测账户限额。