DeepSeek API 错误码查询
按状态码查原因与解法。官方共 7 个错误码，下方全部收录。
400
Invalid Format
请求体格式错误原因：请求体不是合法的 JSON，或缺少必填字段、字段类型不对。
解法：按错误信息提示检查请求体。常见原因：JSON 括号不匹配、messages 不是数组、role 拼错、content 不是字符串。
常见触发：
- 用 requests 直接传 dict 忘了 json= 参数
- messages 里混入了非 dict 元素
401
Authentication Fails
认证失败原因：API Key 错误、缺失、已删除或已失效。
解法：检查 Authorization 头是否为 Bearer
常见触发：
- 把 Key 写进了 URL 而不是 header
- 复制时多了空格或换行
- Key 属于另一个账号
402
Insufficient Balance
余额不足原因：账户余额（含赠送额度）已用完。
解法：到官方控制台查看余额并充值。注意赠送额度有有效期。
常见触发：
- 跑批任务把余额一次性用光
- 赠送额度到期未察觉
422
Invalid Parameters
参数错误原因：请求体是合法 JSON，但参数值不合法：模型名不存在、temperature 越界、max_tokens 过大、消息角色不合法。
解法：核对模型名称拼写与取值范围。max_tokens 不能超过模型输出上限。
常见触发：
- 模型名写成 deepseek-chat 等旧名
- max_tokens 超过 384K
- temperature 填了 3
429
Rate Limit Reached
触发限流原因：请求发送过快，或超过并发/QPS 限制。也可能是账户余额临界或触发风控。
解法：降低发送速率，加指数退避重试。并发上限按模型不同（Flash 2500、V4 Pro 500）。
常见触发：
- 并发请求数超过账号上限
- 短时间重试风暴
- 多实例共用一个 Key
500
Server Error
服务端错误原因：服务端内部异常，与请求内容无关。
解法：稍候重试；持续出现时联系官方支持。建议在客户端做重试机制。
常见触发：
- 偶发的内部异常
- 上游依赖故障
503
Server Overloaded
服务过载原因：流量高峰导致服务端过载，无法处理请求。
解法：稍候重试。避开高峰时段（北京时间 09:00-12:00、14:00-18:00）可显著降低遇到 503 的概率。
常见触发：
- 工作时段高并发时段
- 免费额度集中使用时段
哪些错误该重试，哪些不该
| 错误 | 是否重试 | 原因 |
|---|---|---|
| 400 / 422 | 不重试 | 请求本身有问题，重试也不会成功，必须改代码 |
| 401 | 不重试 | Key 有问题，修好再用 |
| 402 | 不重试 | 余额不足，充值后继续 |
| 429 | 退避重试 | 限流，指数退避通常能过 |
| 500 / 503 | 退避重试 | 服务端问题，等的价值大于改代码 |
429 与 503 的实际区别
429 是你的问题：并发超限或发送过快。Flash 并发上限 2500、V4 Pro 500，多实例共用一个 Key 时最容易撞上。做法是在客户端加全局并发控制，而不是让每个实例自己重试。
503 跟你无关：服务端过载。避开高峰时段（北京时间 09:00-12:00、14:00-18:00）能显著降低遇到概率——这也是 离峰省钱 的附带好处。
退避重试的实现要点
指数退避：第一次等 1 秒，之后 2、4、8、16 秒，最多重试 4-5 次。加随机抖动（±20%）避免多个客户端同时重试造成二次风暴。只对 429/500/503 重试，400/401/402/422 重试没有意义。