错误码
当 API 请求失败时，ClawdRouter 会返回标准的 HTTP 状态码和错误信息。
对于视频等异步任务，需要额外注意：请求被受理成功，并不代表任务最终一定成功。
HTTP 状态码
| 状态码 | 说明 | 处理建议 |
|---|---|---|
202 | 请求已受理，任务异步处理中 | 常见于视频等异步任务；继续到任务中心查看最终结果 |
200 | 请求成功 | — |
400 | 请求参数错误 | 检查请求体格式和参数是否正确 |
401 | 认证失败 | 检查 API Key 是否正确，Authorization Header 格式是否为 Bearer YOUR_API_KEY |
403 | 权限不足 | API Key 无权访问该模型或资源 |
404 | 资源不存在 | 检查请求路径和模型名称是否正确 |
429 | 请求频率超限 | 降低请求频率，参考限制 |
500 | 服务器内部错误 | 服务端异常，请稍后重试或提交工单联系技术支持 |
502 | 网关错误 | 上游服务暂时不可用，请稍后重试 |
503 | 服务不可用 | 服务正在维护或过载，请稍后重试 |
202 Accepted 不是错误202 Accepted 代表平台已经成功受理请求，后续会异步继续处理。对于视频生成等能力，最终是否成功要结合任务状态、结果状态和回调状态一起判断。
错误响应格式
{
"error": {
"message": "Invalid API Key provided",
"type": "authentication_error",
"code": "invalid_api_key"
}
}
| 字段 | 说明 |
|---|---|
error.message | 错误描述 |
error.type | 错误类别 |
error.code | 错误码 |
常见错误类型
authentication_error
认证相关错误。
| 错误码 | 说明 | 解决方法 |
|---|---|---|
invalid_api_key | API 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 | 配额用尽 | 检查账户余额或提升配额 |
异步任务排查提示
如果你调用的是视频等异步接口，建议按下面顺序排查：
- 先看 HTTP 状态是否已受理，例如
202 Accepted - 再到控制台任务中心查看任务结果
- 若任务失败，再回到日志管理确认请求层、回调层和计费层信息
重试策略建议
对于可重试的错误（429、500、502、503），建议实施 指数退避 策略：
import time
import random
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="__DOCS_API_ORIGIN__/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)