API 错误排查
API 错误排查中心
API 错误排查中心汇总 OpenAI-compatible API、SDK、Codex、网络和配置层面的常见错误，帮助定位 401、403、404、429、5xx、上下文、模型和流式问题。
API 报错时，不要先改一大段业务代码。更可靠的方法是把问题缩小到六个层面： Key、Base URL、模型名、请求参数、网络链路和服务端状态。
这页是 OfApp.cn 知识库的错误排查入口，只写通用 OpenAI-compatible API、SDK 和网络排查方法，不假设 OfApp.cn 内部错误码。涉及 OfApp.cn 的具体模型、能 力、额度、价格和控制台提示，请以 OfApp.cn 控制台或官方文档为准。
| 项目 | 说明 |
|---|---|
| 阅读时间 | 约 5 分钟 |
| 更新时间 | 2026-07-02 |
| 适合读者 | AI 初学者、开发者、运维、产品经理、正在接入 AI API 的团队 |
| 适合任务 | 排查 401、403、404、429、5xx、模型、上下文、流式中断和 SDK 配置 |
这页解决什么
Section titled “这页解决什么”错误排查中心不是错误码字典，而是一条定位路径。读完这页，你应该能判断：
| 你看到的现象 | 应该先查哪里 |
|---|---|
| 请求立刻失败 | Key、Bearer 请求头、Base URL、端点路径 |
| 只有某个模型失败 | 模型名、模型类型、账号权限、控制台可用范围 |
| 本地能跑，部署失败 | 环境变量、Secret、代理、服务器网络 |
| 批处理跑一半失败 | 并发、429、quota、重试放大、输入长度 |
| 流式输出到一半断开 | SSE、代理缓冲、超时、客户端取消、5xx |
| 同一请求偶发失败 | 网络抖动、临时服务端错误、有限退避重试 |
| 错误 | 常见触发 | 优先排查 |
|---|---|---|
| 401 鉴权失败排查 | 未通过鉴权 | API Key、Bearer 请求头、环境变量、Base URL |
| invalid API key | Key 无效或不匹配 | Key 格式、复制错误、Base URL 和 Key 来源 |
| 403 Forbidden 错误排查 | 身份可识别但无权访问 | 权限、项目、模型、地区和策略限制 |
| 404 Not Found 错误排查 | 路径或资源不存在 | Base URL、/v1、端点、HTTP 方法、资源 ID |
| model not found 错误排查 | 模型不可用或类型不匹配 | 模型名、模型类型、端点和控制台可用范围 |
| 429 Rate Limit | 请求过快或额度受限 | 并发、输入长度、quota、退避重试 |
| insufficient quota | 可用额度不足或项目限制 | 控制台、Key 归属、请求成本、重试放大 |
| 500 Server Error 错误排查 | 服务端或链路临时错误 | 5xx 分类、请求 ID、最小复现、退避重试 |
| 上下文长度超限错误排查 | 输入或历史上下文过长 | Token、历史消息、工具结果、RAG 召回、输出长度 |
| 流式响应中断排查 | 流式响应中断 | SSE、代理缓冲、超时、部分内容保存、客户端取消 |
通用排查顺序
Section titled “通用排查顺序”- 记录状态码、错误类型、最终请求 URL、端点、模型名和请求时间。
- 脱敏保存响应体、请求 ID、SDK 版本、部署环境和网络环境。
- 用最小 curl 请求复现，排除业务代码、框架和 SDK 封装干扰。
- 检查
OPENAI_BASE_URL、OPENAI_API_KEY和OPENAI_MODEL是否来自同一套配置。 - 删除非必要参数，只保留最小 messages、input 或 prompt。
- 根据状态码进入对应错误页，而不是在一个函数里反复猜。
- 对 429、408、409、5xx 和连接错误使用有限退避；对 401、403、404、参数和模型错误先修配置。
最小复现模板
Section titled “最小复现模板”排查 OpenAI-compatible API 时，先用最小请求确认入口是否可用。OfApp.cn 文档
展示的兼容 Base URL 为 https://api.ofapp.cn/v1；如果你的客户端会自动拼
接 /v1，请以当前客户端和 OfApp.cn 官方文档为准。
export OPENAI_BASE_URL="https://api.ofapp.cn/v1"export OPENAI_API_KEY="sk-xxxx"export OPENAI_MODEL="以控制台可用模型为准"
curl -sS "$OPENAI_BASE_URL/chat/completions" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$OPENAI_MODEL"'", "messages": [ { "role": "user", "content": "ping" } ] }'如果最小请求失败，优先修 Key、Base URL、端点和模型名。如果最小请求成功， 再回到 SDK、Codex CLI、代理、部署环境或业务参数里排查。
状态码怎么判断
Section titled “状态码怎么判断”| 类型 | 含义 | 常见处理 |
|---|---|---|
| 400 | 请求体、参数或格式不符合要求 | 打印脱敏请求摘要，删除复杂参数 |
| 401 | 服务端没有接受身份凭证 | 检查 Key、Bearer 头和环境变量 |
| 403 | 身份识别成功，但访问被拒绝 | 检查权限、项目、模型和策略 |
| 404 | URL、端点或资源不存在 | 检查 Base URL、/v1 和端点路径 |
| 408 / 409 | 超时或短暂冲突 | 有限重试，记录上下文 |
| 429 | 请求频率、并发、quota 或资源限制 | 降并发、缩输入、退避和控制台复核 |
| 5xx | 服务端或链路临时错误 | 保存请求 ID，最小复现，有限重试 |
| 网络错误 | DNS、代理、TLS、网关或连接失败 | 换网络、查代理、设 timeout |
OpenAI 官方错误码指南建议用程序化方式处理 APIError、APIConnectionError 和 RateLimitError。限流指南还提醒，失败请求也会占用每分钟限制窗口，所以连续 快速重发不是解决办法。
不要盲目重试
Section titled “不要盲目重试”| 可以有限重试 | 不适合盲目重试 |
|---|---|
| 408、409、429、5xx | 401、403、404 |
| APIConnectionError、网络抖动 | invalid API key |
| 短暂代理或网关异常 | model not found |
| 批处理里的临时失败项 | insufficient quota 或明确项目限制 |
重试应该有最大次数、指数退避、随机抖动和失败队列。更完整的实现可以看 错误重试示例。
日志脱敏清单
Section titled “日志脱敏清单”| 应记录 | 不应记录 |
|---|---|
| 状态码、错误类型、请求 ID | API Key、Cookie、完整 Authorization 头 |
| Base URL 域名、端点路径 | 真实用户隐私、合同、论文全文、内部文件 |
| 模型名、SDK 版本、运行环境 | 未脱敏的数据库记录和业务密钥 |
| attempt、timeout、重试次数 | 完整长 Prompt 和敏感附件 |
| 输入长度摘要、并发数 | 生产账单、套餐截图、账号凭据 |
把日志交给 AI 或 Codex 排查前，先替换 Key、手机号、邮箱、姓名、订单号、内 部域名和业务内容。排查需要的是结构化线索，不是完整隐私材料。
常见排查路径
Section titled “常见排查路径”| 场景 | 推荐路径 |
|---|---|
| 新手第一次接入 | 获取 API Key → Base URL → OpenAI-compatible API |
| SDK 报错 | OpenAI SDK 接入 → curl 示例 → 对应错误页 |
| Codex CLI 报错 | Codex CLI 接入 OfApp.cn → 常见错误排查 |
| 频率或额度问题 | 429 Rate Limit → insufficient quota → 错误重试示例 |
| 长文或日志失败 | 上下文长度超限 → Embeddings 与 RAG 检索示例 |
| 流式输出中断 | streaming interrupted → OpenAI API 流式输出示例 |
- OpenAI API 错误码指南：说明常见 API 错误类型，并建议程序化处理 APIError、APIConnectionError 和 RateLimitError。
- OpenAI Rate limits 指南：建议对限流使用随机指数退避，并说明失败请求也会计入限制窗口。
- OfApp.cn API 直转文档：展示 OfApp.cn 的 OpenAI 兼容入口、Key、Base URL 和示例请求；具体模型、能力、额度和价格请以控制台或官方文档为准。
API 报错时应该先看状态码还是错误文本？
Section titled “API 报错时应该先看状态码还是错误文本？”两个都要看。状态码决定排查方向，错误文本提供具体线索。401、403、404 更 偏配置和权限；429 更偏频率、并发或额度；5xx 和连接错误更偏临时故障或网 络链路。
最小 curl 请求成功，SDK 仍然失败怎么办？
Section titled “最小 curl 请求成功，SDK 仍然失败怎么办？”优先检查 SDK 的 baseURL 或 base_url、环境变量加载、代理、timeout、重
试设置和最终请求路径。很多 SDK 问题不是 Key 错，而是路径被重复拼接或部署
环境没有读取到新配置。
429 和 insufficient quota 是一回事吗？
Section titled “429 和 insufficient quota 是一回事吗？”不完全一样。429 是状态码，可能来自短期限流、并发过高、单次请求过重，也 可能和 quota 有关。insufficient quota 更明确指向额度、账号、项目或计划限 制，需要回到控制台和官方文档复核。
5xx 是不是只能等服务商修？
Section titled “5xx 是不是只能等服务商修？”不一定。偶发 5xx 可以有限重试，但如果只有某个请求稳定 5xx，也要检查输入 长度、参数组合、模型类型和端点兼容性。保留请求 ID 和最小复现，排查效率会 高很多。
能不能把完整报错日志直接发给 AI？
Section titled “能不能把完整报错日志直接发给 AI？”不建议。应先脱敏 Key、Cookie、用户隐私、内部 URL、业务字段和附件内容。 给 AI 的材料应包含状态码、端点、模型名、SDK、脱敏响应体、复现步骤和你已 经尝试过的修复。
OfApp.cn 的错误码和 OpenAI 完全一样吗？
Section titled “OfApp.cn 的错误码和 OpenAI 完全一样吗？”不能这样假设。OfApp.cn 提供 OpenAI 兼容入口，但具体模型、能力、额度、错 误体和控制台提示都应以 OfApp.cn 控制台或官方文档为准。本页只提供通用排查 框架。
- 常见错误排查：按 Key、Base URL、模型、SDK、Codex 和网络逐层定位。
- curl 示例：用最小 HTTP 请求复现问题。
- 错误重试示例：处理 429、5xx、超时和连接错误。
- OpenAI-compatible API 快速开始：验证基础配置。
- 用 Codex 排查报错：把脱敏日志交给 Codex 定位代码问题。
- 开发者：查看 API、SDK、示例、迁移和错误排查内容边界。
API 错误排查的关键不是背错误码，而是把问题缩小到可验证的层面。先用最小请 求确认 Key、Base URL、端点和模型名，再按状态码进入对应错误页。对配置、权 限、模型和参数问题先修配置；对限流、网络和服务端临时错误才做有限退避重试。