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

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

作者：IsAnythingDown. 核对于 2026-10-06.

规范页面： https://isanythingdown.com/zh-cn/guides/ai-api-error-codes

## 简要回答

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

## 从错误类别开始

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

| 你看到的内容 | 首先检查 | 不能确认什么 |
| --- | --- | --- |
| 400 / 404 / 413 | 请求格式、端点、资源及大小；请读取提供方错误 | 一般服务故障 |
| 401 / 403 | 凭据、访问权限与提供方特定限制 | 所有用户都无法访问 |
| 429 | 限速响应头、配额、积分与支出限制 | 立即重试就会成功 |
| 500 / 503 / 529 | 提供方错误详情与相关官方组件 | 已确认的全局事件 |
| 超时 / 连接错误 | 客户端截止时间、DNS、TLS、代理及请求时长 | 哪一方造成失败 |
- [OpenAI API 错误码](https://developers.openai.com/api/docs/guides/error-codes)
- [Claude API 错误](https://platform.claude.com/docs/en/api/errors)
- [Gemini API 排查](https://ai.google.dev/gemini-api/docs/troubleshooting)

## OpenAI：429 可能对应不同限制

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

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

- [OpenAI API 错误码](https://developers.openai.com/api/docs/guides/error-codes)
- [OpenAI API 组件报告](https://isanythingdown.com/zh-cn/services/openai)

## Claude：过载与支出上限不同

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

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

- [Claude API 错误](https://platform.claude.com/docs/en/api/errors)

## Gemini：核对开发者端点

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

- [Gemini API 排查](https://ai.google.dev/gemini-api/docs/troubleshooting)
- [Gemini API / AI Studio 官方状态](https://aistudio.google.com/status)

## 为重试设置预算

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

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

- [OpenAI API 错误码](https://developers.openai.com/api/docs/guides/error-codes)
- [Gemini API 排查](https://ai.google.dev/gemini-api/docs/troubleshooting)

## 排查具体响应

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

- [AI API 错误 429](https://isanythingdown.com/zh-cn/guides/ai-api-error-429)
- [AI API 错误 500](https://isanythingdown.com/zh-cn/guides/ai-api-error-500)
- [AI API 错误 503](https://isanythingdown.com/zh-cn/guides/ai-api-error-503)
- [AI API 错误 529](https://isanythingdown.com/zh-cn/guides/ai-api-error-529)

## 相关服务页面

- [OpenAI API](https://isanythingdown.com/zh-cn/services/openai)
- [Claude](https://isanythingdown.com/zh-cn/services/claude)
- [Gemini API / AI Studio](https://isanythingdown.com/zh-cn/services/gemini-api)
- [OpenRouter](https://isanythingdown.com/zh-cn/services/openrouter)

每个条目显示自己的采集覆盖。链接到服务不一定表示自动采集。

编辑审核日期适用于本指南。实时报告采集时间显示在服务页面。