跳到主要内容

错误码

当 API 请求失败时，ClawdRouter 会返回标准的 HTTP 状态码和错误信息。

HTTP 状态码​

状态码说明处理建议
200请求成功—
400请求参数错误检查请求体格式和参数是否正确
401认证失败检查 API Key 是否正确，Authorization Header 格式是否为 Bearer YOUR_API_KEY
403权限不足API Key 无权访问该模型或资源
404资源不存在检查请求路径和模型名称是否正确
429请求频率超限降低请求频率，参考速率限制
500服务器内部错误服务端异常，请稍后重试或提交工单联系技术支持
502网关错误上游服务暂时不可用，请稍后重试
503服务不可用服务正在维护或过载，请稍后重试

错误响应格式​

{
  "error": {
    "message": "Invalid API Key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
字段说明
error.message错误描述
error.type错误类别
error.code错误码

常见错误类型​

authentication_error​

认证相关错误。

错误码说明解决方法
invalid_api_keyAPI Key 无效确认 API Key 是否正确，是否已过期或被禁用
missing_api_key缺少 API Key在请求头中添加 Authorization: Bearer YOUR_API_KEY

invalid_request_error​

请求参数错误。

错误码说明解决方法
invalid_model模型不存在检查 model 参数值是否在模型列表中
invalid_messages消息格式错误检查 messages 数组格式是否正确
context_length_exceeded上下文长度超限减少输入消息内容或使用支持更长上下文的模型

rate_limit_error​

频率限制错误。

错误码说明解决方法
rate_limit_exceeded请求频率超限降低请求频率，实施指数退避重试策略
quota_exceeded配额用尽检查账户余额或提升配额

重试策略建议​

对于可重试的错误（429、500、502、503），建议实施 指数退避 策略：

import time
import random
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.clawdrouter.com/v1",
)

def call_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=[{"role": "user", "content": "你好"}],
            )
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            wait_time = (2 ** attempt) + random.random()
            print(f"请求失败，{wait_time:.1f}s 后重试...")
            time.sleep(wait_time)