错误码与症状索引

HTTP 401 — AI API 返回 401 Unauthorized 怎么办症状：请求未通过身份验证

HTTP 403 — AI API 返回 403 Forbidden 怎么办症状：身份可能已识别，但操作被拒绝

HTTP 429 — AI API 返回 429：速率限制与配额排查症状：请求过多或配额不足

TIMEOUT — AI 模型请求超时：从客户端到上游逐层排查症状：连接、首字节或完整响应超过时限

DNS / TLS — AI API 连接失败：DNS 与 TLS 错误怎么排查症状：请求在收到 HTTP 响应前因域名解析或 TLS 握手失败

TIMEOUT — DeepSeek API 请求超时：连接、读取与流式中断排查症状：请求在连接、等待首字节、读取响应或流式传输过程中超过客户端期限或中断

HTTP 500 — AI API 返回 500：服务端错误如何安全排查症状：服务端处理请求时发生未预期错误

HTTP 529 — Claude API 返回 529 Overloaded Error 怎么解决症状：Anthropic API 暂时过载，返回 overloaded_error

CONTEXT LENGTH — 上下文长度超限：输入太长时怎么处理症状：请求因输入与预期输出所需令牌超过模型上下文窗口而被拒绝

HTTP 400 — Gemini API 返回 400 INVALID_ARGUMENT 怎么排查症状：Gemini API 指出请求正文格式不正确、字段缺失或参数与端点不匹配

JSON PARSE — AI API 响应 JSON 解析失败：定位与修复症状：客户端收到响应，但 JSON 解析器报语法错误或数据结构不符合预期

HTTP 502 — AI API 返回 502 Bad Gateway 怎么排查症状：网关或反向代理未能从上游模型服务获得有效响应

HTTP 503 — AI API 返回 503 Service Unavailable 怎么处理症状：服务暂时无法处理请求，可能处于过载、维护或依赖故障状态

MIGRATION — OpenAI-compatible API 迁移失败：base_url、/v1、Chat Completions 与 Responses 路径排查症状：更换兼容服务、SDK 或 API 形态后出现 404、401、400、响应字段不匹配或流式解析错误

GUIDE — AI API 429、503与529有什么区别？判断、重试与排障指南症状：AI API返回 429，通常表示客户端、账号、组织或项目在某个时间窗口内超过请求数、令牌数或并发额度；返回 503，通常表示服务端暂时无法处理请求，例如过载或维护；529 overloadederror 则是Anthropic API明确

GUIDE — AI API 的 HTTP 错误、failed、incomplete、refusal 和 moderation flagged 有什么区别？症状：AI API 的 HTTP 错误、failed、incomplete、refusal 和 moderation flagged 有什么区别？

GUIDE — OpenAI API 返回401怎么排查：密钥、Bearer头、项目归属与代理日志检查症状：OpenAI API 返回401怎么排查：密钥、Bearer头、项目归属与代理日志检查

GUIDE — OpenAI Batch API 的 JSONL、custom_id、input file、output file、error file、completed、expired 和 cancelled 有什么区别？症状：OpenAI Batch API 的 JSONL、customid、input file、output file、error file、completed、expired 和 cancelled 有什么区别？

GUIDE — OpenAI API中的input_tokens、cached_tokens、cache_write_tokens、reasoning_tokens、output_tokens和total_tokens有什么区别？症状：OpenAI API中的inputtokens、cachedtokens、cachewritetokens、reasoningtokens、outputtokens和totaltokens有什么区别？

GUIDE — OpenAI Responses API 的 background、轮询、Webhook、cancel、store 和 ZDR 有什么区别？症状：OpenAI Responses API 的 background、轮询、Webhook、cancel、store 和 ZDR 有什么区别？

GUIDE — OpenAI Responses API 的 input_text、input_image、input_file、URL、Base64、file_id、detail 和 PDF 有什么区别？症状：OpenAI Responses API 的 inputtext、inputimage、inputfile、URL、Base64、fileid、detail 和 PDF 有什么区别？

GUIDE — OpenAI Responses API 的 output、Output Item、Message Content、output_text、Refusal、Annotations 和 Reasoning Item 有什么区别？症状：OpenAI Responses API 的 output、Output Item、Message Content、outputtext、Refusal、Annotations 和 Reasoning Item 有什么区别？

GUIDE — OpenAI Responses API 的 reasoning.effort、text.verbosity、max_output_tokens、truncation、service_tier、prompt_cache_key 和 safety_identifier 有什么区别？症状：OpenAI Responses API 的 reasoning.effort、text.verbosity、maxoutputtokens、truncation、servicetier、promptcachekey 和 safetyide

GUIDE — OpenAI Responses API 的 text.format、json_schema、json_object、strict、required、additionalProperties 和 refusal 有什么区别？症状：OpenAI Responses API 的 text.format、jsonschema、jsonobject、strict、required、additionalProperties 和 refusal 有什么区别？

GUIDE — OpenAI Responses API 的 Web Search、File Search、Code Interpreter、Image Generation、Computer Use 和 Remote MCP 有什么区别？症状：OpenAI Responses API 的 Web Search、File Search、Code Interpreter、Image Generation、Computer Use 和 Remote MCP 有什么区别？

GUIDE — API返回200却JSON解析失败：HTML错误页、空响应与Content-Type排查症状：先不要直接解析JSON。检查最终响应URL和重定向历史，再读取 Content-Type、Content-Encoding 与正文长度；把正文作为文本保存前几百个字符并脱敏。如果Content-Type不是JSON、正文以HTML标签开头或

GUIDE — AI API SSE流式输出卡住、截断或重复：代理缓冲排查指南症状：先绕过代理直连上游，记录首字节时间、每个数据块的到达时间和字节数，再逐层加回 Nginx/CDN/网关。确保成功响应使用与 SSE 一致的 text/event-stream，代理不对该路由做响应缓冲，读取超时大于允许的无数据间隔，且客户端

GUIDE — OpenAI API返回429怎么排查：RPM、TPM、项目限额与指数退避检查清单症状：先记录 HTTP 429、响应中的错误类型与错误码、x-request-id，以及 x-ratelimit-limit-、x-ratelimit-remaining-、x-ratelimit-reset- 响应头。确认请求实际使用的组织、项

GUIDE — OpenAI API上下文长度超限怎么办：输入与输出Token预算排查症状：先保存脱敏后的模型、端点、请求结构、各输入组件大小、输出上限、truncation设置、响应 status/incomplete details、usage和 x-request-id。用与目标模型相符的 Token 计数方式测量系统指令、

GUIDE — OpenAI API请求超时或连接重置怎么办：重试与未知结果排查症状：先保存脱敏后的请求时间、API 路径、模型、SDK 与版本、超时类型、重试次数、流式/非流式、客户端自定义请求 ID，以及响应可用时的 x-request-id。从同一运行环境检查 DNS、TLS、代理和到 API 域名的 HTTPS；把

GUIDE — OpenAI Responses API工具调用call_id不匹配、漏回传或重复执行排查症状：先保存脱敏的 response ID、output item ID、callid、tool name、arguments 摘要、应用 job ID、执行状态和回传请求 ID。将每个 functioncall 按 callid 写入持久状态表

GUIDE — OpenAI Responses API返回incomplete、空output_text或截断：排查指南症状：先记录 HTTP 状态、响应 ID、model、status、incompletedetails、usage、output 中每个 item 的 type/status，以及 message content 的具体类型。若 status=i

GUIDE — OpenAI Responses 后台任务长期 queued：轮询、Webhook 与重复事件排查症状：OpenAI Responses 后台任务长期 queued：轮询、Webhook 与重复事件排查

GUIDE — OpenAI Responses previous_response_id 无效或上下文重复：会话状态排查症状：OpenAI Responses previousresponseid 无效或上下文重复：会话状态排查

GUIDE — OpenAI Responses `store:false` 后上下文丢失：ZDR、加密 reasoning 与 compaction 排查症状：OpenAI Responses store:false 后上下文丢失：ZDR、加密 reasoning 与 compaction 排查

GUIDE — OpenAI Structured Outputs返回400或解析失败：JSON Schema排查指南症状：OpenAI Structured Outputs返回400或解析失败：JSON Schema排查指南

GUIDE — OpenAI Vector Store 文件卡在 in_progress：failed、格式与批次排查症状：OpenAI Vector Store 文件卡在 inprogress：failed、格式与批次排查

GUIDE — AI API流式响应中的delta、done、stop_reason和连接关闭有什么区别？症状：delta是尚在生成过程中的增量片段；内容级 done表示某个文本或内容块已定稿；响应级 completed或最终结束事件表示整个模型响应成功完成；finishreason或 stopreason说明模型为何停止生成；连接关闭只说明传输通道

GUIDE — tool schema、arguments、strict、tool_choice、parallel tool calls和tool output有什么区别？症状：Tool schema是开发者提供给模型的工具定义；arguments是模型为某次函数调用生成的参数字符串；strict要求生成参数遵循受支持的JSON Schema子集；toolchoice控制模型是否可以、必须或只能调用指定工具；par

GUIDE — x-request-id、response.id、conversation、previous_response_id、item id和call_id有什么区别？症状：x-request-id 标识一次 OpenAI API 的 HTTP 请求，适合定位服务端请求日志；response.id 标识 Responses API 创建的一个 Response 资源；conversation 标识可持续保存输入