DeepSeek API 使用标准 HTTP 状态码返回错误。本文列出所有错误码、常见触发原因及对应解决方案，是 API 调用调试的第一参考文档。

DeepSeek API 错误码

错误码一览

HTTP 状态码	含义	常见原因	解决方案
400	请求格式错误	JSON 格式不合法、必填字段缺失、Strict 模式 schema 不规范	检查请求体结构
401	认证失败	API Key 错误、Key 已过期、Header 格式错误	检查 Authorization: Bearer <key>
402	余额不足	账户余额耗尽	充值账户
422	参数错误	参数值超出范围、类型不匹配	检查具体参数值
429	超出限速	请求频率过高	降低请求频率，实现退避重试
500	服务器内部错误	DeepSeek 服务端故障	等待后重试
503	服务不可用	服务器负载过高	等待后重试，监控 状态页

常见错误详解

400 - 请求格式错误

触发场景：

1. JSON 格式不合法

   {"error": {"message": "JSON parse error", "type": "invalid_request_error"}}

   检查请求体是否是合法 JSON，特别是中文字符和特殊字符的转义。

2. Strict 模式 schema 不合规（最常见）

   {"error": {"message": "strict mode requires all properties to be in required"}}

   确认 required 数组包含了所有 properties 的 key，且设置了 "additionalProperties": false。

3. messages 格式错误

   // ❌ 错误：content 不能是 null
   {"role": "user", "content": null}
   
   // ✅ 正确
   {"role": "user", "content": "你好"}

401 - 认证失败

检查清单：

// ❌ 常见错误写法
headers: { "Authorization": "sk-xxxxx" }  // 缺少 "Bearer "

// ✅ 正确写法
headers: { "Authorization": "Bearer sk-xxxxx" }

• 确认 API Key 在 平台控制台 仍然有效（未被删除）
• 确认没有多余的空格或换行

402 - 余额不足

通过 API 查询余额：

curl https://api.deepseek.com/user/balance \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

429 - 超出限速

DeepSeek 对请求频率有限制，推荐实现指数退避重试：

async function callWithRetry(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

限速策略详见：限速说明

500 / 503 - 服务端错误

这类错误与你的请求无关，是 DeepSeek 服务端问题：

• 直接重试，503 通常是短暂的高负载
• 查看 DeepSeek 状态页 确认是否有服务中断
• 在重试逻辑中给 5xx 错误加上退避时间

错误处理模板

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseek.com",
  apiKey: process.env.DEEPSEEK_API_KEY,
});

try {
  const response = await client.chat.completions.create({
    model: "deepseek-v4-pro",
    messages: [{ role: "user", content: "你好" }],
  });
  return response.choices[0].message.content;
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    switch (error.status) {
      case 400: console.error("请求格式错误:", error.message); break;
      case 401: console.error("API Key 无效"); break;
      case 402: console.error("余额不足，请充值"); break;
      case 429: console.error("超出限速，请稍后重试"); break;
      case 500:
      case 503: console.error("服务端错误，稍后重试"); break;
    }
  }
  throw error;
}

常见问题

Q: 收到 400 但不知道哪里出问题，怎么定位？

A: 查看 error response 中的 message 字段，一般有具体说明。最常见的是 Strict 模式 schema 违规（required 不完整）和 messages 格式问题。

Q: 429 错误发生后等多久再重试合适？

A: 建议从 1 秒开始，每次失败翻倍（1s → 2s → 4s），最多重试 3~5 次。也可以读取 response header 中的 Retry-After 字段（若有）。

Q: 500 和 503 有什么区别？

A: 503 通常是服务器负载过高的临时状态，几秒到几分钟后会自动恢复；500 是未预期的服务端错误，持续出现时可联系 api-service@deepseek.com。