API 错误码详解与处理方案
全面了解API错误码，掌握错误处理最佳实践，构建稳定可靠的应用
快速识别
准确判断错误类型
优雅处理
友好的错误提示
智能重试
自动恢复机制
详细记录
问题追踪分析
一、常见错误码速查表
400 - Bad Request
请求格式错误或参数无效
常见原因：
- • JSON格式错误
- • 必需参数缺失
- • 参数类型错误
- • 参数值超出范围
解决方案：
- ✓ 检查请求体JSON格式
- ✓ 验证所有必需参数
- ✓ 确认参数类型正确
- ✓ 查看API文档了解限制
401 - Unauthorized
认证失败或凭证无效
常见原因：
- • API Key错误或缺失
- • API Key已过期
- • 认证头格式错误
- • API Key未激活
解决方案：
- ✓ 检查Authorization头
- ✓ 确认API Key正确
- ✓ 重新生成API Key
- ✓ 验证Bearer token格式
403 - Forbidden
无权访问请求的资源
常见原因：
- • 账户余额不足
- • API Key权限不足
- • 访问受限的模型
- • 账户被暂停
解决方案：
- ✓ 检查账户余额
- ✓ 确认API权限设置
- ✓ 升级到合适的计划
- ✓ 联系客服解决
404 - Not Found
请求的资源不存在
常见原因：
- • API端点URL错误
- • 模型名称错误
- • API版本不正确
- • 资源已被删除
解决方案：
- ✓ 检查请求URL拼写
- ✓ 确认模型名称
- ✓ 使用正确的API版本
- ✓ 查看最新API文档
429 - Too Many Requests
请求频率超过限制
常见原因：
- • 超过RPM限制
- • 超过TPM限制
- • 并发请求过多
- • 短时间大量请求
解决方案：
- ✓ 实施请求限流
- ✓ 使用指数退避
- ✓ 批量处理请求
- ✓ 升级使用限制
500 - Internal Server Error
服务器内部错误
常见原因：
- • 服务器处理异常
- • 内部服务故障
- • 资源耗尽
- • 未知系统错误
解决方案：
- ✓ 稍后重试请求
- ✓ 记录错误ID
- ✓ 联系技术支持
- ✓ 检查服务状态
二、统一错误处理
基础错误处理器
import requests
from typing import Optional, Dict
import json
import time
class APIErrorHandler:
"""统一的API错误处理器"""
def __init__(self):
self.error_handlers = {
400: self._handle_bad_request,
401: self._handle_unauthorized,
403: self._handle_forbidden,
404: self._handle_not_found,
429: self._handle_rate_limit,
500: self._handle_server_error,
503: self._handle_service_unavailable
}
def handle_api_call(self, func, *args, **kwargs) -> Optional[Dict]:
"""处理API调用并统一处理错误"""
try:
response = func(*args, **kwargs)
# 检查HTTP状态码
if response.status_code == 200:
return response.json()
# 调用对应的错误处理器
handler = self.error_handlers.get(
response.status_code,
self._handle_unknown_error
)
return handler(response)
except requests.exceptions.ConnectionError:
print("❌ 连接错误：无法连接到API服务器")
return None
except requests.exceptions.Timeout:
print("⏱️ 超时错误：请求超时，请稍后重试")
return None
except Exception as e:
print(f"🚨 未知错误：{str(e)}")
return None
def _handle_bad_request(self, response):
"""处理400错误 - 请求参数错误"""
error_data = response.json()
error_msg = error_data.get('error', {}).get('message', '请求参数错误')
print(f"❌ 400错误：{error_msg}")
# 解析具体错误类型
if "model" in error_msg:
print(" 💡 提示：检查模型名称是否正确")
elif "max_tokens" in error_msg:
print(" 💡 提示：max_tokens参数超出限制")
elif "messages" in error_msg:
print(" 💡 提示：消息格式错误，检查role和content")
return None
def _handle_unauthorized(self, response):
"""处理401错误 - 认证失败"""
print("🔐 401错误：API Key无效或已过期")
print(" 💡 提示：")
print(" 1. 检查API Key是否正确")
print(" 2. 确认API Key是否已激活")
print(" 3. 检查是否使用了正确的认证头")
return None
def _handle_forbidden(self, response):
"""处理403错误 - 权限不足"""
error_data = response.json()
error_code = error_data.get('error', {}).get('code', '')
if error_code == 'insufficient_quota':
print("💳 403错误：账户余额不足")
print(" 💡 提示：请充值后继续使用")
else:
print("🚫 403错误：没有权限访问此资源")
print(" 💡 提示：检查API Key的权限设置")
return None
def _handle_not_found(self, response):
"""处理404错误 - 资源不存在"""
print("🔍 404错误：请求的资源不存在")
print(" 💡 提示：")
print(" 1. 检查API端点URL是否正确")
print(" 2. 确认模型名称是否存在")
print(" 3. 验证API版本是否正确")
return None
def _handle_rate_limit(self, response):
"""处理429错误 - 限流"""
retry_after = response.headers.get('Retry-After', 60)
print(f"⏳ 429错误：触发限流，请等待{retry_after}秒")
# 显示限流信息
limit = response.headers.get('X-RateLimit-Limit')
remaining = response.headers.get('X-RateLimit-Remaining')
if limit:
print(f" 📊 限流信息：限制 {limit}/分钟，剩余 {remaining}")
return None
def _handle_server_error(self, response):
"""处理500错误 - 服务器内部错误"""
print("💥 500错误：服务器内部错误")
print(" 💡 提示：")
print(" 1. 稍后重试")
print(" 2. 如果问题持续，联系技术支持")
# 记录详细错误信息用于调试
error_id = response.headers.get('X-Request-ID')
if error_id:
print(f" 🆔 错误ID：{error_id}")
return None
def _handle_service_unavailable(self, response):
"""处理503错误 - 服务不可用"""
print("🔧 503错误：服务暂时不可用")
print(" 💡 提示：")
print(" 1. 服务可能正在维护")
print(" 2. 等待几分钟后重试")
# 检查维护信息
maintenance_info = response.headers.get('X-Maintenance-Until')
if maintenance_info:
print(f" ⏰ 预计恢复时间：{maintenance_info}")
return None
def _handle_unknown_error(self, response):
"""处理未知错误"""
print(f"❓ {response.status_code}错误：未知错误类型")
try:
error_data = response.json()
print(f" 📝 错误详情：{json.dumps(error_data, indent=2)}")
except:
print(f" 📝 响应内容：{response.text[:200]}...")
return None
# 使用示例
handler = APIErrorHandler()
def make_api_request():
return requests.post(
"https://api.n1n.ai/v1/chat/completions",
headers={"Authorization": "Bearer your-key"},
json={
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}]
}
)
result = handler.handle_api_call(make_api_request)