ERROR LIBRARY
AI API、Codex 与 Claude Code 错误排查库
从状态码或原始错误出发，按请求、认证、模型、网络、网关与客户端配置逐层定位。每篇都包含最小复现、修复验证和日志脱敏边界。
统一诊断顺序
- 01
保存原始证据
状态码、错误体、request ID、UTC 时间和客户端版本。
- 02
缩成最小请求
固定主机、Key 与模型，一次只移除或恢复一个变量。
- 03
定位响应层
区分客户端、网络代理、CodeNodex 网关与模型上游。
- 04
验证与脱敏
重复验证恢复范围，分享前删除凭据与业务数据。
API 响应错误
按 HTTP 状态码区分请求、认证、模型、限流与上游服务异常。
OpenAI API 400 Bad Request：参数、JSON 与请求格式排查
定位 OpenAI 兼容 API 的 400 Bad Request，检查 JSON、模型参数、接口路径和客户端序列化，并用最小请求验证修复。
查看诊断步骤HTTP 401API 401 Invalid API Key：Codex、Claude Code 与 SDK 认证排查
排查 API 401 Invalid API Key，区分 Key 无效、请求头不匹配、Base URL 错误和客户端凭据来源，并安全轮换凭据。
查看诊断步骤HTTP 403API 403 Forbidden：权限、账号状态与策略拒绝排查
定位 API 403 Forbidden，区分已认证但无模型权限、账号或项目状态、组织策略和网关访问控制。
查看诊断步骤HTTP 404API 404 Model Not Found：模型 ID、Base URL 与路由排查
排查 API 404 和 Model Not Found，确认最终接口路径、模型 ID、provider 映射及账号可见模型。
查看诊断步骤HTTP 429API 429 Rate Limit：限流、余额与退避重试排查
解决 API 429 Rate Limit，区分请求速率、Token 配额、余额不足与并发限制，并实施带抖动的指数退避。
查看诊断步骤HTTP 500API 500 Internal Server Error：请求重试与上游定位
排查 API 500 Internal Server Error，保留 request ID、缩减请求、识别可重试场景并确认错误来自网关还是上游。
查看诊断步骤HTTP 502API 502 Bad Gateway：代理、上游与响应格式排查
定位 API 502 Bad Gateway，区分边缘代理、CodeNodex 网关和模型上游的连接或无效响应，并建立有限重试。
查看诊断步骤HTTP 503API 503 Service Unavailable：过载、维护与恢复验证
排查 API 503 Service Unavailable，区分维护、过载、健康检查和模型容量问题，尊重 Retry-After 并安全恢复流量。
查看诊断步骤网络与流式传输
定位超时、连接重置、TLS 证书和 SSE 流式响应中断。
API 请求超时：连接、首字节、生成与客户端时限排查
分层排查 API request timeout、ETIMEDOUT 和 deadline exceeded，区分 DNS、连接、首字节、流式空闲与总时限。
查看诊断步骤ECONNRESETAPI ECONNRESET / Connection Reset：连接被重置排查
排查 ECONNRESET、connection reset by peer 和 socket hang up，定位客户端连接池、代理、TLS 与上游提前断开。
查看诊断步骤TLS / SSLAPI SSL Certificate Error：证书链、主机名与代理排查
排查 API SSL certificate error、CERT_HAS_EXPIRED 和 certificate verify failed，检查系统时间、主机名、证书链与企业代理。
查看诊断步骤SSE STREAMOpenAI API Stream Disconnected：SSE 流式响应中断排查
排查 OpenAI 兼容 API 的 SSE stream disconnected、提前 EOF 和缺少结束事件，检查客户端消费、代理缓冲和重连边界。
查看诊断步骤客户端与配置
处理上下文超限、Codex、Claude Code Gateway 与 MCP 启动问题。
Context Length Exceeded：上下文窗口超限排查与修复
解决 context_length_exceeded 和 maximum context length 错误，核算输入、工具、历史与输出预算，并安全压缩上下文。
查看诊断步骤CODEX TOMLCodex config.toml Parse Error：未知字段、层级与严格配置排查
排查 Codex config.toml parse error、unknown field、重复键和配置不生效，安全备份并使用 strict config 验证。
查看诊断步骤CLAUDE GATEWAYClaude Code Gateway Connection Error：URL、认证与模型路由排查
排查 Claude Code LLM Gateway 连接错误，检查 ANTHROPIC_BASE_URL、Bearer/x-api-key、Messages 路径、模型映射和 SSE。
查看诊断步骤MCP SERVERMCP Server Failed to Start：进程、传输、认证与工具发现排查
排查 MCP server failed to start、连接失败和工具不可见，区分 stdio 进程、HTTP 传输、认证、协议初始化与客户端权限。
查看诊断步骤