# 排查 LLM API 错误与重试

## 重试前先保存证据

记录 UTC 时间、端点、公开模型 ID、HTTP 状态、返回的请求 ID（如有），以及是否已收到输出。保存脱敏后的错误摘要，不在共享日志中记录 API Key、认证头、私密提示词或完整用户请求。

通过[模型查询](/zh/docs/common-api)确认路由，通过[协议选择](/zh/docs/llm/protocols)确认请求格式。媒体任务状态与 LLM HTTP 错误的恢复方式不同。

| 现象 | 优先检查 | 下一步 |
| --- | --- | --- |
| 400 或参数校验错误 | 必填字段、模型专用参数、上下文与输出限制 | 修改请求后再调用 |
| 401 | 密钥是否有效、认证头是否正确 | 修复认证，不原样重试 |
| 403 | Key 权限或访问策略 | 与账号所有者确认权限 |
| 404 | 公开模型 ID、协议端点、SDK 最终 URL | 查询目录，排除重复 `/v1` |
| 429 | 速率、账号限制、实际错误信息 | 降低并发；如返回 `Retry-After` 则遵守 |
| 5xx | 脱敏错误和请求 ID | 排查服务或上游故障，限制恢复次数 |
| 超时或流式断线 | 是否已经产生输出与用量 | 将完成状态视为不确定，不直接判定未执行 |

这张表是排查起点，不代替原生错误信息。同一状态码可能有多种原因；429 也不意味着充值就能解决。

## 在应用边界限制重试

只重试已被应用判定为暂时性的问题。采用带随机抖动的指数退避，同时设置较小的最大次数、整体截止时间与总费用预算，达到任一边界就停止。如有 `Retry-After` 应遵守，但不能假设所有响应都包含该头。

添加外层重试循环前检查 SDK 默认行为，避免多层重试成倍增加请求。不要在失败时悄悄切换模型，能力和输出变化可能使用户任务或评测失效。

生成请求超时后仍可能已执行。本指南不假设 LLM POST 端点支持幂等，也不假设相同请求体会自动去重费用。收到部分结果后，应保留内容，由应用或用户决定如何恢复，不自动重放。

## 提交可用于定位的问题报告

提供最小脱敏请求结构、端点、模型 ID、带时区的时间、状态码、请求 ID 与复现情况，不包含凭据和客户内容。用量应标记为已观察、缺失或待确认，不能把缺少回执写成零费用。

新接入应用可退回[最小请求](/zh/docs/llm/first-request)；仅流式场景出错时检查[事件解析与完成信号](/zh/docs/llm/streaming)。批准更多重试实验前，先阅读[费用核算](/zh/docs/llm/cost-and-usage)。