官方文档
排障手册HTTP状态码运维指南
更新于 2026-11-18 · 约 5 分钟读完
大模型 API 常见 HTTP 状态码(401/402/403/429/529)快速排障手册
全面汇总调用 OpenAI、Anthropic Claude、Gemini 接口时常见的 HTTP 状态码含义、定位方法与客户端重试最佳实践。
状态码速查总表
| HTTP 状态码 | 错误分类 | 核心原因 | 推荐处理方案 |
|---|---|---|---|
400 Bad Request | 请求格式错误 | JSON 字段不合法、max_tokens 超上限或协议选错 | 核对端点协议(如 Claude 原生参数发往 /v1/messages) |
401 Unauthorized | 身份鉴权失败 | sk-... 密钥拼写错误、已被停用或请求头缺失 | 前往 免登录密钥测活 一键校验密钥有效性 |
402 / 403 Forbidden | 额度或权限受限 | 账户余额不足、子密钥配额用尽、IP 不在白名单或分组不含该模型 | 检查控制台余额、子密钥配额进度条及绑定分组 |
429 Too Many Requests | 速率或并发限流 | 超过账户最大并发路数或触发子密钥 5h/日滚动限额 | 客户端启用指数退避重试,或在控制台调高限速策略 |
502 / 503 / 529 | 上游瞬时拥塞 | 官方上游算力高峰期瞬时抖动 | 网关已内置毫秒级自动容灾切换,客户端重试一次即可恢复 |
如何在控制台自助查看具体报错详情?
登录 开发者控制台 后,点击左侧菜单 「📜 调用账单 → 异常请求排查」,即可直接查看近期非 200 请求的时间戳、目标模型、HTTP 状态码与具体错误摘要,无需盲目猜测。
生产环境 SDK 指数退避重试代码示例
python
from openai import OpenAI
# 官方 SDK 默认自带 max_retries=2 指数退避,生产环境建议设为 3
client = OpenAI(
base_url="https://portal-production-81780394.up.railway.app/v1",
api_key="sk-your-key",
max_retries=3,
timeout=120.0,
)
🚀 准备好在项目中极速接入了吗?
注册即可创建专属 API Key,原生直连 Claude 4.5、GPT-5 Codex 与 Gemini 2.5 Pro。