错误处理指南
了解 Mint Cloud AI API 的错误响应格式、状态码和最佳实践,帮助你构建健壮的应用程序。
错误响应格式
所有 API 错误都遵循统一的 JSON 格式,便于程序化处理:
{
"error": {
"code": "rate_limit_exceeded",
"message": "请求频率超过限制,请稍后重试",
"type": "rate_limit_error"
}
}code
错误码,标识错误的类型
message
人类可读的错误描述
type
错误类型分类
HTTP 状态码
API 使用标准 HTTP 状态码来表示请求结果:
| 状态码 | 说明 | 常见原因 |
|---|---|---|
| 200 | 成功 | 正常响应 |
| 400 | 请求错误 | 参数格式错误、缺少必填字段 |
| 401 | 认证失败 | API Key 无效或过期 |
| 403 | 权限不足 | 账户无权访问该模型 |
| 404 | 资源不存在 | 模型 ID 错误 |
| 429 | 触发限流 | 超过速率限制 |
| 500 | 服务器错误 | 内部错误,请重试 |
| 502 | 上游错误 | 模型供应商服务异常 |
| 503 | 服务不可用 | 服务维护中 |
错误码类型
API 返回的错误码用于标识具体错误类型:
authentication_error
认证失败,API Key 无效或已过期
invalid_request
请求参数格式错误或缺少必填字段
rate_limit_exceeded
请求频率超过限制,请等待后重试
server_error
服务器内部错误,通常是临时性的
invalid_api_key
API Key 不存在或已被禁用
model_not_found
请求的模型不存在或无权访问
错误处理示例
以下示例展示如何在 Python 中处理各种 API 错误:
Python 错误处理
import time
from openai import RateLimitError, AuthenticationError, APIError
def call_api_with_retry(client, model, messages, max_retries=3):
"""带重试的 API 调用"""
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model=model,
messages=messages
)
return response
except RateLimitError:
# 处理限流,等待后重试
wait_time = 2 ** attempt # 指数退避
print(f"触发限流,等待 {wait_time} 秒后重试...")
time.sleep(wait_time)
except AuthenticationError:
# API Key 无效
print("认证失败:请检查 API Key 是否正确")
raise
except APIError as e:
# 其他 API 错误
print(f"API 错误:{e}")
if attempt == max_retries - 1:
raise
time.sleep(1)
# 使用示例
try:
result = call_api_with_retry(
client=client,
model="openai/gpt-4o",
messages=[{"role": "user", "content": "你好"}]
)
print(result.choices[0].message.content)
except Exception as e:
print(f"请求最终失败:{e}")重试策略
指数退避
每次重试之间等待的时间成倍增加,例如:1秒、2秒、4秒、8秒。 这可以避免在服务器负载高时进一步压垮服务。
有限重试次数
设置最大重试次数(通常 3-5 次),避免无限重试。 超过最大次数后,记录错误并向用户报告。
区分错误类型
限流错误(429)适合重试,认证错误(401)不应重试, 服务器错误(500、502、503)可以重试。
添加抖动
在退避时间上添加随机抖动(0.5-1秒),避免多客户端同时重试造成雷鸣羊群效应。
最佳实践
1
始终检查响应状态
不要假设请求一定成功,在处理响应前检查状态码和错误字段。
2
提供有意义的错误信息
将技术错误转化为用户友好的提示,帮助用户理解问题并采取行动。
3
记录完整错误上下文
记录错误码、错误信息、请求参数和时间戳,便于排查问题和监控系统。
4
实现优雅降级
当 API 不可用时,提供备选方案或缓存数据,确保核心功能可用。
5
使用超时设置
为所有 API 请求设置合理的超时时间,避免无限等待导致的程序卡死。