源力AI

主题

错误码参考 ​

源力AI 使用标准 HTTP 状态码表示请求结果，错误响应体遵循 OpenAI 格式，便于现有错误处理逻辑直接复用。

错误响应格式 ​

所有错误响应均以 JSON 格式返回：

json
{
  "error": {
    "message": "Invalid authentication credentials.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
字段说明
message人类可读的错误描述
type错误类型分类
param导致错误的请求参数（如适用）
code机器可读的错误代码

HTTP 状态码详解 ​

400 Bad Request — 请求格式错误 ​

含义： 请求体格式错误、缺少必填参数、参数值无效。

常见原因：

  • messages 字段为空数组或格式不符合规范
  • model 参数指定了不存在的模型 ID
  • temperature 超出合法范围（0~2）
  • max_tokens 设置了负数或超大值
  • 请求体不是有效的 JSON

错误响应示例：

json
{
  "error": {
    "message": "[] is too short - 'messages'",
    "type": "invalid_request_error",
    "param": "messages",
    "code": null
  }
}

解决方案：

  • 检查请求体是否为合法 JSON（注意引号、逗号）
  • 确认 messages 数组至少包含一条消息
  • 对照 模型列表 确认模型 ID 拼写正确
  • 验证所有数值参数在合法范围内

401 Unauthorized — 认证失败 ​

含义： API Key 无效、格式错误或未提供。

常见原因：

  • 未在请求头中携带 Authorization 字段
  • Authorization 头格式错误（应为 Bearer sk-xxx，注意有空格）
  • API Key 已被删除或不存在
  • 复制密钥时包含了多余空格

错误响应示例：

json
{
  "error": {
    "message": "Incorrect API key provided: sk-xxxx. You can find your API key at https://bww.letcareme.com.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

解决方案：

bash
# 正确格式
curl -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" ...

# 错误：缺少 Bearer 前缀
curl -H "Authorization: sk-xxxxxxxxxxxxxxxxxxxxxxxx" ...

# 错误：多余空格
curl -H "Authorization: Bearer  sk-xxxxxxxxxxxxxxxxxxxxxxxx" ...
  • 登录控制台确认密钥存在且处于启用状态
  • 重新复制密钥，避免首尾空白字符

403 Forbidden — 权限不足 ​

含义： 密钥有效但被禁用，或账户存在限制。

常见原因：

  • API Key 在控制台被手动禁用
  • 账户余额不足，无法继续请求
  • 尝试调用无权访问的模型

错误响应示例：

json
{
  "error": {
    "message": "Your API key has been disabled. Please check your account status.",
    "type": "invalid_request_error",
    "param": null,
    "code": "api_key_disabled"
  }
}

解决方案：

  • 登录控制台 → API 密钥，检查密钥状态
  • 登录控制台 → 钱包，检查账户余额，及时充值
  • 如账户状态异常，请联系 bookwormweb@163.com

429 Too Many Requests — 超出速率限制 ​

含义： 在短时间内发送了过多请求，触发速率限制。

常见原因：

  • 高频并发请求超过每分钟限额（RPM）
  • 单次请求的 token 数量超过每分钟 token 限额（TPM）
  • 短时间内大量并发请求

错误响应示例：

json
{
  "error": {
    "message": "Rate limit reached for gpt-4o in organization on requests per min. Limit: 60, Used: 60.",
    "type": "requests",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

解决方案：

python
import time
import random
from openai import RateLimitError

def chat_with_backoff(client, messages, max_retries=5):
    """带指数退避的重试逻辑"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            # 指数退避 + 随机抖动，避免同时重试
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"速率限制，{wait:.1f} 秒后重试...")
            time.sleep(wait)
  • 降低并发请求数量
  • 实现请求队列，控制发送频率
  • 使用指数退避重试策略

500 Internal Server Error — 服务端内部错误 ​

含义： 源力AI 服务端发生未预期的错误。

常见原因：

  • 模型服务临时异常
  • 上游 AI 提供商返回异常响应
  • 系统处理请求时遇到未知错误

错误响应示例：

json
{
  "error": {
    "message": "The server had an error while processing your request. Sorry about that!",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

解决方案：

  • 等待 1~5 秒后重试，通常是临时性故障
  • 如持续出现，请发送邮件至 bookwormweb@163.com 并附上请求时间和错误信息

502 Bad Gateway — 网关错误 ​

含义： 源力AI 网关无法连接到上游模型提供商服务。

常见原因：

  • 上游模型服务（OpenAI / Anthropic 等）临时中断
  • 网络路由问题
  • 上游服务维护

解决方案：

  • 等待几分钟后重试
  • 临时切换到其他可用模型（如从 gpt-4o 切换到 claude-3-5-sonnet-20241022）
  • 查看上游服务状态页了解是否有官方公告

503 Service Unavailable — 服务不可用 ​

含义： 源力AI 服务暂时不可用，通常因为过载或计划维护。

错误响应示例：

json
{
  "error": {
    "message": "The engine is currently overloaded, please try again later.",
    "type": "server_error",
    "param": null,
    "code": "server_overloaded"
  }
}

解决方案：

  • 等待 10~60 秒后重试
  • 使用指数退避策略自动重试
  • 持续不可用时联系客服

错误处理最佳实践 ​

完整错误处理示例 ​

python
from openai import (
    OpenAI,
    APIError,
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    InternalServerError,
)
import time
import random

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://bww.letcareme.com/v1"
)

def safe_chat(messages: list, model: str = "gpt-4o", max_retries: int = 3) -> str:
    retryable_errors = (RateLimitError, InternalServerError)
    
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
                timeout=30  # 设置超时
            )
            return response.choices[0].message.content

        except AuthenticationError as e:
            # 认证错误：不重试，直接报错
            raise RuntimeError(f"API Key 无效，请检查密钥配置: {e}") from e

        except BadRequestError as e:
            # 请求格式错误：不重试，修复参数后再试
            raise RuntimeError(f"请求参数错误: {e.message}") from e

        except retryable_errors as e:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"[第 {attempt+1} 次重试] {type(e).__name__}，等待 {wait:.1f}s...")
            time.sleep(wait)

        except APIError as e:
            # 其他 API 错误
            if e.status_code and e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

    raise RuntimeError("超出最大重试次数")

错误码速查表 ​

HTTP 状态码错误类型是否可重试建议操作
400Bad Request否修复请求参数
401Unauthorized否检查 API Key
403Forbidden否检查密钥状态/余额
429Rate Limited是指数退避重试
500Server Error是等待后重试
502Bad Gateway是等待后重试
503Service Unavailable是等待后重试

联系支持 ​

如果错误持续出现且无法自行解决，请通过以下方式联系我们：

  • 邮件：bookwormweb@163.com
  • 请附上：请求时间、使用的模型、错误信息完整内容、请求 ID（响应头 x-request-id）

按量计费 · 即开即用 · 稳定可靠

© 2026 源力AI (YuanForce) · bookwormweb@163.com