直接答案
500 表示处理请求时出现未预期异常；客户端应保存关联证据并有限重试，而不是不断修改 Key 或无限重放。
这篇内容解决什么问题
解决 internal_server_error、server_error 和偶发 HTTP 500，并建立安全的重试与升级路径。
OpenAI 兼容 APIAnthropic 兼容 API同步与流式请求SDK 与 curl
01
先确认症状与影响范围
请求返回 500 Internal Server Error、server_error 或网关包装的内部错误。相同请求偶发成功通常指向瞬时服务异常；相同输入稳定失败可能由特定参数或上游处理路径触发。
先确认响应确实来自 API，而不是本地代理、企业网关或应用自己的后端。响应头、request ID 和时间点用于关联服务端日志。
- 记录精确 UTC 时间、状态码、request ID、模型 ID 和接口路径。
- 确认失败是全部请求、单一模型还是某个输入稳定触发。
- 确认请求是否已产生输出或副作用，决定能否安全重试。
02
常见原因与责任边界
500 的具体异常通常只能由生成该响应的服务日志确认。客户端侧的目标是定位响应方、构造最小复现并避免重试扩大故障。
- 上游模型服务或网关出现瞬时内部异常。
- 特定请求参数、工具定义或输入触发未处理边界。
- 内部依赖失败被统一包装成 500。
- 客户端连接已收到部分结果，但包装层错误地改写为 500。
03
按层执行最小诊断
先用同一模型执行最小文本请求，再用原请求复现。若最小请求成功，逐步恢复参数；若全部模型都失败，检查服务状态并暂停自动流量。
不要通过打印完整请求内容换取“更多日志”。服务端定位通常只需要 request ID、时间、模型、路径和脱敏的最小结构。
- 01确认响应方检查主机、Content-Type、响应头与 request ID。
- 02最小请求使用一条无工具、无图片的文本请求做对照。
- 03模型对照在允许范围内比较另一已知可用模型，确认影响面。
- 04停止放大失败率持续升高时熔断批处理和自动重试。
保存状态码、响应头和响应体语言：bash
date -u
curl -sS -D /tmp/api-500.headers -o /tmp/api-500.body -w 'status=%{http_code} total=%{time_total}
' 'https://<your-api-host>/v1/models' -H "Authorization: Bearer ${API_KEY:?set API_KEY first}"
04
针对根因完成修复
偶发 500 可对可安全重放的请求实施少量指数退避；稳定复现则应保留最小输入并升级服务方。客户端输入导致的稳定 500 不应通过无限重试掩盖。
- 01有限重试设置最大尝试次数、总时限和随机抖动。
- 02隔离触发项逐项恢复 tools、图片、结构化输出和长上下文。
- 03服务降级按业务策略暂停、排队或切换到已验证的可用模型。
- 04提交证据提供 request ID、UTC 时间和脱敏最小复现。
05
验证修复而不是只看一次成功
连续执行有限次数的最小请求并观察错误率，而不是以单次 200 宣布恢复。恢复完整请求后还要确认没有重复输出或重复计费。
- 最小请求与原业务请求均在观察窗口内稳定成功。
- 重试有上限并记录最终失败。
- 带副作用的调用具备幂等键或人工确认。
06
安全边界与升级证据
升级服务方时不要提交真实 Key、用户消息或工具参数中的秘密。若怀疑请求内容触发异常，先构造不含私人数据的等价最小输入。
- 不无限重放可能计费或有副作用的请求。
- 不在公共状态页面或 Issue 暴露账号信息。
- 保留 request ID 与时间，不保留 Authorization。
官方来源与核验范围
本文以协议规范和客户端官方文档为事实依据。错误文案、重试头和配置字段可能随服务或客户端版本变化；执行前请核对来源，并对日志与请求样例脱敏。
查看技术核验方法