指南
错误码
当 API 请求失败时，响应将包含一个 HTTP 状态码以及详细描述错误信息的 JSON 错误体。本页面汇总了所有可能的错误码及其处理方式。
错误响应格式
所有错误均遵循统一的 JSON 格式：
JSON
{
"error": {
"message": "A human-readable description of the error.",
"type": "error_type",
"param": "the_parameter_that_caused_the_error",
"code": "machine_readable_error_code"
}
}| 字段 | 说明 |
|---|---|
| message | 面向用户阅读的错误描述 |
| type | 便于程序处理的错误分类 |
| param | 导致错误的参数（不适用时为 null） |
| code | 便于程序识别具体错误的机器可读错误码 |
状态码总览
| 状态码 | 名称 | 说明 | 可重试 |
|---|---|---|---|
| 400 | Bad Request | 请求格式错误，或缺少必需参数。 | 否 |
| 401 | Unauthorized | 鉴权失败。您的 API Key 缺失、无效或已过期。 | 否 |
| 402 | Payment Required | 您的账户余额不足，无法处理本次请求。 | 否 |
| 403 | Forbidden | 您的 API Key 无权访问所请求的资源。 | 否 |
| 429 | Too Many Requests | 您已超出该 API Key 的 Rate Limit（每分钟请求数或每分钟 Token 数）。 | 是 |
| 500 | Internal Server Error | 服务器发生预期之外的错误。 | 是 |
| 503 | Service Unavailable | 服务暂时不可用，通常是因为上游模型 Provider 出现故障或过载。 | 是 |
错误码详解
推荐的重试策略
对于可重试的错误（429、500、503），建议实现带抖动的指数退避策略：
Python
import time
import random
from openai import OpenAI, RateLimitError, APIError
client = OpenAI(
base_url="https://api.tokenfast.ai/v1",
api_key="sk-your-api-key"
)
def make_request_with_retry(max_retries=5):
for attempt in range(max_retries):
try:
return client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
except RateLimitError as e:
if attempt == max_retries - 1:
raise
# 带抖动的指数退避
wait = min(2 ** attempt + random.random(), 60)
print(f"Rate limited. Retrying in {wait:.1f}s...")
time.sleep(wait)
except APIError as e:
if e.status_code and e.status_code >= 500:
if attempt == max_retries - 1:
raise
wait = min(2 ** attempt + random.random(), 60)
print(f"Server error. Retrying in {wait:.1f}s...")
time.sleep(wait)
else:
raise