API 调用失败怎么办

API 调用失败时，不要只反复重试。先按 API 地址、认证信息、模型、请求格式、余额和日志顺序检查。

排查顺序

1. 确认 API 地址完整，路径和版本与客户端要求一致。
2. 确认请求头使用 Authorization: Bearer YOUR_API_KEY，并替换了占位符。
3. 确认 API 密钥仍处于启用状态，没有过期或超过限制。
4. 确认 model 填写的是账户可用模型名称。
5. 确认请求正文是合法 JSON，必填字段和数据类型正确。
6. 查看账户余额或订阅额度，排除额度不足。
7. 查看使用日志，记录请求 ID 和错误原因。
8. 如果错误提示与频率有关，阅读限流问题。

使用不同客户端时的检查重点

客户端类型	重点检查
curl 或脚本	API 地址是否包含正确路径、引号和 JSON 格式是否完整。
OpenAI 兼容客户端	Base URL、API Key 和模型名称是否分别填入正确字段。
IDE 或命令行工具	环境变量是否在启动工具前已经生效。
Playground	账户、模型和额度是否可用；在线测试不需要把密钥粘贴到聊天内容中。

常见状态码

状态码	初步理解
400	请求内容有问题，例如 JSON 格式或参数不正确。
401	身份认证失败，常见原因是 API 密钥错误、过期或未正确发送。
403	当前账户或密钥没有执行该操作的权限。
404	API 地址、接口路径或模型名称不存在。
429	请求太频繁，触发 RPM、TPM 或其他限流。
500	平台或上游服务发生服务器错误，需要结合请求 ID排查。

关键概念

关键词	含义和用途
API 密钥	程序调用 API 时用于身份认证的秘密凭证。
Base URL	客户端配置的基础 API 地址，接口路径通常追加在它后面。
模型	请求中 model 字段指定的 AI 服务名称。
请求 ID	一次调用的唯一编号，联系支持人员时应提供它。
Quota	本次调用可能扣除的账户额度单位。

安全提醒

提交错误信息时可以提供请求 ID和脱敏后的错误内容，但不要提供完整 API 密钥、密码、验证码或包含隐私的原始提示词。