跳到主要内容

错误码字典

本文档列出 Real200 API 的所有错误码、触发原因和解决方法。

错误格式​

{
  "error": {
    "message": "错误描述信息",
    "type": "错误类型",
    "code": "错误码",
    "param": "相关参数（如有）"
  }
}

4xx 客户端错误​

400 Bad Request — invalid_request_error​

原因： 请求参数不符合 API 规范。

常见场景：

  • model 参数为空或不存在
  • messages 为空数组
  • temperature 超出范围 (0–2)
  • JSON 格式不正确

解决方法： 检查请求参数，参考Chat Completions API。

401 Unauthorized — invalid_api_key / invalid_authentication​

原因： API Key 无效或认证失败。

常见场景：

  • API Key 格式不正确
  • API Key 已被禁用或删除
  • Authorization Header 格式错误

解决方法：

  1. 确认 API Key 以 sk-real200- 开头
  2. 确认 Authorization: Bearer <key> 格式正确
  3. 在控制台检查 Key 状态

402 Payment Required — insufficient_quota​

原因： 账户余额不足或 Key 额度用尽。

解决方法：

  • 充值账户
  • 检查并提高 Key 的配额上限
  • 联系管理员

403 Forbidden — permission_denied​

原因： 当前用户没有权限访问该资源。

解决方法： 联系管理员提升权限。

404 Not Found — not_found​

原因： 请求的资源不存在。

常见场景：

  • 模型名称拼写错误
  • 端点路径错误

解决方法： 检查模型名称和端点路径，参考模型列表。

429 Too Many Requests — rate_limit_exceeded​

原因： 请求频率超过限制。

详见： 限流策略

重试策略：

import time
from openai import OpenAI

client = OpenAI(api_key="sk-real200-xxx", base_url="https://real200.com/v1")

for attempt in range(3):
    try:
        response = client.chat.completions.create(model="gpt-4o", messages=[...])
        break
    except Exception as e:
        if "429" in str(e):
            wait = 2 ** attempt  # 指数退避：2s, 4s, 8s
            time.sleep(wait)
        else:
            raise

5xx 服务端错误​

500 Internal Server Error — api_error​

原因： Real200 服务端内部错误。

解决方法：

  1. 等待片刻后重试
  2. 检查供应商状态（可能所有供应商都不可用）
  3. 如持续发生，联系技术支持

502 Bad Gateway — bad_gateway​

原因： 供应商返回无效响应。

解决方法： 通常自动恢复。智能路由会自动切换到其他供应商。

503 Service Unavailable — service_unavailable​

原因： 供应商暂时不可用。

解决方法： 智能路由会自动切换到备用供应商。

自定义错误码​

错误码说明解决方法
upstream_error供应商 API 返回错误检查供应商状态，智能路由会自动重试
token_filter请求/响应内容触发敏感词过滤修改请求内容
model_unavailable指定模型暂时不可用尝试其他模型名称

错误处理最佳实践​

  1. 始终检查 HTTP 状态码：不要只依赖响应体
  2. 实现指数退避重试：对 429 和 5xx 错误使用指数退避
  3. 记录错误日志：记录 error.type、error.code 和请求参数
  4. 设置超时：请求超时建议 30–60 秒
  5. 监控错误率：当错误率异常升高时，及时告警