适用于模型 API 调用失败、超时或收到 200 却没有完整结果。按失败层次、服务方错误类型和最少元信息定位问题，再做一次有边界的复查。
内容更新 2026-07-26状态码只是线索：先确认谁返回、失败在哪一层，再区分配置错误、额度限制和临时故障；不要一见报错就换 Key 或重发。
{
"example": "fictional_support_summary",
"client": "ExampleClient 1.0",
"timeWithZone": "2026-08-01T10:30:00+08:00",
"authType": "third_party_api_key",
"httpStatus": 429,
"errorCode": "rate_limit_exceeded",
"concurrency": 1,
"action": "pause_and_check_retry_policy"
}| 现象 | 先核对的证据 | 最小处理与复查 |
|---|---|---|
| 401 | Key 是否属于该服务；认证字段是否发送；项目/组织与有效期是否匹配 | 修正一项配置或授权选择后再试；不默认重新生成 Key。 |
| 403 | 服务给出的权限或策略原因；模型/接口授权；组织规则 | 由有权限的人确认是否允许。地域或账号限制按平台规则处理，不绕过。 |
| 404 | 最终路径有无重复 /v1；请求是否采用正确协议；模型/资源是否存在且可访问 | 按该客户端版本文档修正路径或资源标识。不要给所有客户端统一补 /v1。 |
| 429 | rate limit、余额耗尽、用量或 spend limit 的具体错误类型 | 频率限制才退避；余额/用量/硬限额先人工处理，不自动充值或抬限额。 |
| 503 | 是否为网关维护或上游过载；Retry-After；相同时间的服务说明 | 停止批量任务，等待后最多追加一次小请求；切模型不是默认第一步。 |
| 522（Cloudflare） | 是否确实由 Cloudflare 返回；源站连接及确认超时信息 | 可能在 TCP 建立前，也可能建立后等不到源站确认；由服务方查源站，不凭状态码重装客户端。 |
| 524（Cloudflare） | 源站连接已建立；读响应或写请求是否超时 | 由服务方核对超时边界；长任务可另拟较短请求，但先确认原请求是否已执行或计费。 |
| 200 后失败 | 完整 JSON / 流式终止事件、错误事件、客户端处理和业务结果 | 200 只描述响应开始/状态；逐层确认结构、正常结束及所需输出，不能仅凭 200 验收。 |
OpenAI 区分余额耗尽、组织用量、组织/项目硬限额和请求速率。Spend alert 只提醒，启用硬限额才会阻断适用请求；传播有延迟，不承诺分毫不超。Claude API 的错误分类也不同，不能只用一张 HTTP 对照表跨服务下结论。
按字段手工整理白名单摘要；不要附原始响应、请求体、完整日志或配置。下面全部是占位模板。
工具与版本：<名称、版本、操作系统>
接入方式：<订阅登录 / 官方 API Key / 第三方 API Key>
服务公开域名：<无查询参数、无内部地址>
协议与路径类别：<Chat Completions / Responses / Messages>
失败时间与时区：<时间>
HTTP 状态与公共错误代码：<状态、error.code/type；不贴 message>
并发与重试：<数量、是否由 SDK 重试>
已查到的层次：<本机 / API / 网关 / 业务渠道 / 尚不确定>
已改变的一项设置：<只写字段名和变化类别，不写秘密>
请提出证据最少、影响最小的检查，并分别说明修改与验收。
不要索取凭据、Key 片段、原始请求、客户内容或完整日志。