错误处理

错误响应格式

当 API 请求失败时，会返回以下格式的错误响应：

{
  "error": {
    "message": "错误描述信息",
    "type": "error_type",
    "code": "error_code"
  }
}

常见错误码

认证错误 (401)

错误码	说明	解决方案
`invalid_api_key`	API 令牌无效	检查令牌是否正确
`expired_api_key`	API 令牌已过期	创建新的令牌
`missing_api_key`	未提供 API 令牌	在请求头中添加 Authorization

# 正确的认证方式
curl https://api.smai.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key"

请求错误 (400)

错误码	说明	解决方案
`invalid_request`	请求格式错误	检查请求参数
`invalid_model`	模型不存在	使用正确的模型名称
`context_length_exceeded`	上下文超出限制	减少输入内容

配额错误 (429)

错误码	说明	解决方案
`rate_limit_exceeded`	请求频率超限	降低请求频率
`insufficient_quota`	余额不足	充值账户

余额不足

当账户余额不足时，API 将返回 429 错误。请及时充值以继续使用服务。

服务器错误 (500/503)

错误码	说明	解决方案
`server_error`	服务器内部错误	稍后重试
`service_unavailable`	服务暂时不可用	稍后重试
`model_overloaded`	模型负载过高	稍后重试或换用其他模型

错误处理示例

from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.smai.ai/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4.1",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError as e:
    print(f"认证失败: {e}")
except RateLimitError as e:
    print(f"请求频率超限: {e}")
except APIError as e:
    print(f"API 错误: {e}")

重试策略

对于临时性错误（如 429、503），建议实现指数退避重试：

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.smai.ai/v1"
)

def call_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4.1",
                messages=messages
            )
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 1, 2, 4 秒
                print(f"请求频率超限，{wait_time}秒后重试...")
                time.sleep(wait_time)
            else:
                raise

HTTP 状态码汇总

状态码	说明
200	请求成功
400	请求参数错误
401	认证失败
403	权限不足
404	资源不存在
429	请求频率超限或余额不足
500	服务器内部错误
503	服务暂时不可用

获取帮助

如果您遇到无法解决的错误，请联系客服：

微信客服: SmallAI2024
提供错误信息和请求 ID 以便快速定位问题

目录