排查 LLM API 错误与重试

重试前先保存证据

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

通过模型查询确认路由，通过协议选择确认请求格式。媒体任务状态与 LLM HTTP 错误的恢复方式不同。

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

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

在应用边界限制重试

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

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

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

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

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

新接入应用可退回最小请求；仅流式场景出错时检查事件解析与完成信号。批准更多重试实验前，先阅读费用核算。