错误码

了解 Token Hub API 返回的错误类型及处理方式

错误响应格式

所有 API 错误均遵循 OpenAI 兼容的错误响应格式，包含 message、type 和 code 三个字段：

错误响应结构
{
  "error": {
    "message": "错误描述",
    "type": "错误类型",
    "code": "错误代码"
  }
}

提示

建议在代码中对每种错误类型进行区分处理，以实现自动重试、降级等策略。

错误类型总览

HTTP 状态码 type code 说明
401 authentication_error missing_api_key 缺少 API Key
401 authentication_error invalid_api_key API Key 无效
403 permission_error key_disabled API Key 已禁用
403 permission_error insufficient_quota 余额不足
429 rate_limit_error rate_limit_exceeded 超出速率限制
429 rate_limit_error daily_limit_exceeded 超出每日调用限制
400 invalid_request_error model_not_found 模型不存在
400 invalid_request_error invalid_parameters 参数无效
502 provider_error provider_unavailable 供应商不可用
500 server_error internal_error 内部错误

认证错误 (401)

missing_api_key — 缺少 API Key

请求头中未包含 Authorization 字段或 Bearer 令牌为空。

请求示例（缺少 Key）
curl https://api.dandyai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'
响应示例
{
  "error": {
    "message": "No API key provided. Please include a valid API key in the Authorization header.",
    "type": "authentication_error",
    "code": "missing_api_key"
  }
}

invalid_api_key — API Key 无效

提供的 API Key 格式不正确或不存在。

响应示例
{
  "error": {
    "message": "The provided API key is invalid. Please check your key and try again.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

注意

API Key 以 sk- 开头，请确保完整复制，不要包含多余空格。

权限错误 (403)

key_disabled — API Key 已禁用

该 API Key 已被管理员禁用或手动停用。

响应示例
{
  "error": {
    "message": "This API key has been disabled. Contact support if you believe this is an error.",
    "type": "permission_error",
    "code": "key_disabled"
  }
}

insufficient_quota — 余额不足

账户余额不足，无法继续调用 API。请前往控制台充值。

响应示例
{
  "error": {
    "message": "Your account balance is insufficient. Please top up your account to continue using the API.",
    "type": "permission_error",
    "code": "insufficient_quota"
  }
}

限流错误 (429)

rate_limit_exceeded — 超出速率限制

请求频率超出当前套餐的 RPM 限制。响应头 X-RateLimit-Reset 包含限流重置时间（Unix 时间戳）。

响应示例
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718000000

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 5 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

daily_limit_exceeded — 超出每日调用限制

当日 API 调用次数已达到套餐上限，将在次日 0 点（UTC+8）重置。

响应示例
{
  "error": {
    "message": "Daily usage limit reached. Your limit will reset at midnight (UTC+8).",
    "type": "rate_limit_error",
    "code": "daily_limit_exceeded"
  }
}

请求错误 (400)

model_not_found — 模型不存在

请求的模型名称不存在或不在当前套餐可用范围内。

响应示例
{
  "error": {
    "message": "The model 'gpt-5' does not exist or is not available for your account.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

invalid_parameters — 参数无效

请求参数不合法，如 temperature 超出范围、max_tokens 为负数等。

响应示例
{
  "error": {
    "message": "Invalid value for 'temperature': must be between 0 and 2.",
    "type": "invalid_request_error",
    "code": "invalid_parameters"
  }
}

服务端错误 (5xx)

provider_unavailable — 供应商不可用 (502)

上游模型供应商暂时不可用，建议稍后重试。此错误不计费。

响应示例
{
  "error": {
    "message": "The upstream provider is temporarily unavailable. Please retry your request after a brief wait.",
    "type": "provider_error",
    "code": "provider_unavailable"
  }
}

internal_error — 内部错误 (500)

服务端发生内部错误。此错误不计费，如果持续出现请联系技术支持。

响应示例
{
  "error": {
    "message": "An internal error occurred. Our team has been notified. Please try again later.",
    "type": "server_error",
    "code": "internal_error"
  }
}

错误处理建议

错误类型 建议处理方式
认证错误 (401) 检查 API Key 是否正确配置，确保以 sk- 开头
权限错误 (403) 检查 Key 状态及账户余额，必要时充值或联系管理员
限流错误 (429) 实现指数退避重试，读取 Retry-After 响应头
请求错误 (400) 检查请求参数，修正后重试
服务端错误 (5xx) 自动重试（最多 3 次，间隔递增），持续失败则联系支持

重试策略示例

指数退避重试（Python）
import time
import openai

client = openai.OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.dandyai.com/v1"
)

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Hello"}]
        )
        print(response.choices[0].message.content)
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # 指数退避: 1s, 2s, 4s
        print(f"Rate limited, retrying in {wait}s...")
        time.sleep(wait)
    except openai.APIStatusError as e:
        if e.status_code >= 500:
            wait = 2 ** attempt
            print(f"Server error {e.status_code}, retrying in {wait}s...")
            time.sleep(wait)
        else:
            raise