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

DeepSeek API 错误码 #

错误码一览 #

常见错误详解 #

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。