错误代码参考

DeepSeek API 使用标准的 HTTP 状态码和自定义错误代码来表示请求结果。本文档详细介绍了所有可能的错误类型、原因和解决方案。

HTTP 状态码

2xx 成功状态码

状态码	说明	描述
200	OK	请求成功
201	Created	资源创建成功

4xx 客户端错误

状态码	说明	描述	常见原因
400	Bad Request	请求参数错误	参数格式不正确、缺少必需参数
401	Unauthorized	认证失败	API 密钥无效或缺失
403	Forbidden	权限不足	账户权限不足或配额用尽
404	Not Found	资源不存在	请求的端点或资源不存在
422	Unprocessable Entity	请求格式正确但无法处理	参数值超出范围或不符合要求
429	Too Many Requests	请求频率超限	超过速率限制

5xx 服务器错误

状态码	说明	描述	处理建议
500	Internal Server Error	服务器内部错误	稍后重试
502	Bad Gateway	网关错误	检查网络连接，稍后重试
503	Service Unavailable	服务不可用	服务维护中，稍后重试
504	Gateway Timeout	网关超时	请求超时，稍后重试

错误响应格式

所有错误响应都遵循统一的格式：

{
  "error": {
    "message": "错误描述信息",
    "type": "错误类型",
    "code": "错误代码",
    "param": "相关参数（可选）"
  }
}

详细错误代码

认证错误 (Authentication Errors)

invalid_api_key

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

原因: API 密钥格式错误或无效 解决方案:

1. 检查 API 密钥格式是否正确（应以 sk- 开头）
2. 确认密钥长度为 51 字符
3. 验证密钥是否已激活且未过期

api_key_expired

{
  "error": {
    "message": "API key has expired",
    "type": "invalid_request_error",
    "code": "api_key_expired"
  }
}

原因: API 密钥已过期 解决方案: 创建新的 API 密钥

insufficient_quota

{
  "error": {
    "message": "You exceeded your current quota",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

原因: 账户配额不足 解决方案:

1. 检查账户余额
2. 升级订阅计划
3. 等待配额重置

请求错误 (Request Errors)

invalid_request_error

{
  "error": {
    "message": "Invalid request format",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": "messages"
  }
}

常见原因:

• 请求体格式不正确
• 缺少必需参数
• 参数类型错误

model_not_found

{
  "error": {
    "message": "The model 'invalid-model' does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

原因: 指定的模型不存在 解决方案: 使用有效的模型名称（如 deepseek-chat、deepseek-reasoner）

context_length_exceeded

{
  "error": {
    "message": "This model's maximum context length is 32768 tokens",
    "type": "invalid_request_error",
    "code": "context_length_exceeded"
  }
}

原因: 输入内容超过模型的最大上下文长度 解决方案:

1. 减少输入文本长度
2. 分割长文本进行多次请求
3. 使用支持更长上下文的模型

invalid_parameter_value

{
  "error": {
    "message": "Invalid value for parameter 'temperature'",
    "type": "invalid_request_error",
    "code": "invalid_parameter_value",
    "param": "temperature"
  }
}

原因: 参数值超出有效范围 解决方案: 检查参数值是否在允许范围内

速率限制错误 (Rate Limit Errors)

rate_limit_exceeded

{
  "error": {
    "message": "Rate limit reached for requests",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

原因: 超过 API 调用频率限制 解决方案:

1. 实现指数退避重试策略
2. 降低请求频率
3. 升级到更高的速率限制套餐

服务器错误 (Server Errors)

server_error

{
  "error": {
    "message": "The server had an error while processing your request",
    "type": "server_error",
    "code": "server_error"
  }
}

原因: 服务器内部错误 解决方案: 稍后重试，如果问题持续请联系技术支持

service_unavailable

{
  "error": {
    "message": "The engine is currently overloaded",
    "type": "server_error",
    "code": "service_unavailable"
  }
}

原因: 服务暂时不可用 解决方案: 等待几分钟后重试

错误处理最佳实践

1. 实现重试机制

import time
import random
from openai import OpenAI

def api_call_with_retry(client, max_retries=3, base_delay=1):
    """带重试机制的 API 调用"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="deepseek-chat",
                messages=[{"role": "user", "content": "Hello"}]
            )
            return response
            
        except Exception as e:
            error_code = getattr(e, 'code', None)
            
            # 对于某些错误类型不进行重试
            if error_code in ['invalid_api_key', 'model_not_found', 'insufficient_quota']:
                raise e
            
            # 最后一次尝试失败
            if attempt == max_retries - 1:
                raise e
            
            # 指数退避
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

2. 错误分类处理

def handle_api_error(error):
    """根据错误类型进行分类处理"""
    error_code = getattr(error, 'code', None)
    
    if error_code == 'invalid_api_key':
        return "请检查 API 密钥是否正确"
    elif error_code == 'insufficient_quota':
        return "账户配额不足，请充值或升级套餐"
    elif error_code == 'rate_limit_exceeded':
        return "请求频率过高，请稍后重试"
    elif error_code == 'context_length_exceeded':
        return "输入内容过长，请减少文本长度"
    elif error_code == 'model_not_found':
        return "指定的模型不存在，请使用有效的模型名称"
    else:
        return f"未知错误: {error}"

3. 日志记录

import logging

def log_api_error(error, request_data=None):
    """记录 API 错误信息"""
    logging.error(f"API Error: {error}")
    if request_data:
        logging.error(f"Request Data: {request_data}")
    
    # 记录错误详情
    if hasattr(error, 'response'):
        logging.error(f"Response Status: {error.response.status_code}")
        logging.error(f"Response Body: {error.response.text}")

4. 用户友好的错误提示

def get_user_friendly_error(error):
    """将技术错误转换为用户友好的提示"""
    error_messages = {
        'invalid_api_key': '认证失败，请检查您的 API 密钥',
        'insufficient_quota': '账户余额不足，请充值后继续使用',
        'rate_limit_exceeded': '请求过于频繁，请稍后再试',
        'context_length_exceeded': '输入内容过长，请缩短后重试',
        'model_not_found': '模型不可用，请联系技术支持',
        'server_error': '服务暂时不可用，请稍后重试'
    }
    
    error_code = getattr(error, 'code', 'unknown_error')
    return error_messages.get(error_code, '发生未知错误，请联系技术支持')

调试工具

1. 错误诊断脚本

import os
from openai import OpenAI

def diagnose_api_issues():
    """诊断 API 配置问题"""
    print("🔍 开始诊断 API 配置...")
    
    # 检查环境变量
    api_key = os.getenv("DEEPSEEK_API_KEY")
    if not api_key:
        print("❌ 未找到 DEEPSEEK_API_KEY 环境变量")
        return
    
    # 检查密钥格式
    if not api_key.startswith("sk-"):
        print("❌ API 密钥格式错误，应以 'sk-' 开头")
        return
    
    if len(api_key) != 51:
        print(f"❌ API 密钥长度错误，当前长度: {len(api_key)}，应为 51")
        return
    
    print("✅ API 密钥格式正确")
    
    # 测试 API 连接
    try:
        client = OpenAI(
            api_key=api_key,
            base_url="https://api.deepseek.com"
        )
        
        # 测试模型列表
        models = client.models.list()
        print("✅ API 连接正常")
        print(f"✅ 可用模型数量: {len(models.data)}")
        
        # 测试简单请求
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": "test"}],
            max_tokens=1
        )
        print("✅ API 调用成功")
        
    except Exception as e:
        print(f"❌ API 调用失败: {e}")

if __name__ == "__main__":
    diagnose_api_issues()

2. 网络连接测试

import requests
import time

def test_network_connectivity():
    """测试网络连接"""
    endpoints = [
        "https://api.deepseek.com",
        "https://api.deepseek.com/v1/models"
    ]
    
    for endpoint in endpoints:
        try:
            start_time = time.time()
            response = requests.get(endpoint, timeout=10)
            end_time = time.time()
            
            print(f"✅ {endpoint}: {response.status_code} ({end_time - start_time:.2f}s)")
        except Exception as e:
            print(f"❌ {endpoint}: {e}")

常见问题排查

Q: 收到 401 错误怎么办？

A: 401 错误通常表示认证问题：

1. 检查 API 密钥: 确保密钥正确且未过期
2. 检查请求头: 确保 Authorization 头格式正确
3. 检查环境变量: 确认环境变量设置正确

Q: 收到 429 错误怎么办？

A: 429 错误表示请求频率过高：

1. 降低请求频率: 在请求之间添加延迟
2. 实现重试机制: 使用指数退避策略
3. 升级套餐: 考虑升级到更高的速率限制

Q: 收到 500 错误怎么办？

A: 500 错误表示服务器问题：

1. 稍后重试: 等待几分钟后重试
2. 检查服务状态: 访问状态页面确认服务状态
3. 联系支持: 如果问题持续，请联系技术支持

相关资源

• API 认证指南
• 快速开始
• 技术支持
• API 参考文档

---

最后更新: 2025年1月27日