错误处理
常见 HTTP 状态码与排查建议
Gateway 的 /v1*、/v1beta* 接口在出错时，通常返回 OpenAI / Anthropic / Gemini 协议原生错误体（与对应厂商格式一致），便于 SDK 直接解析。
常见状态码
| 状态码 | 含义 | 常见原因 |
|---|---|---|
| 401 | 未授权 | API Key 缺失、格式错误或已失效 |
| 402 | 余额不足 | 钱包可用余额不够，请 充值 |
| 403 | 禁止访问 | 令牌无权访问该模型，或未订阅对应模型 |
| 429 | 请求过多 | 触发配额/限流，稍后重试 |
| 502 | 上游错误 | 模型渠道返回异常 |
| 503 | 服务不可用 | 上游暂时不可用或维护中 |
401 排查
- 确认 Header 为
Authorization: Bearer sk-xxx（注意Bearer与空格） - 确认使用的是 Gateway API Key，不是 Console 登录 JWT
- 在 令牌管理 检查令牌是否被禁用或过期
402 / 403 排查
429 排查
- 降低并发或增加重试间隔（建议指数退避）
- 联系管理员确认租户配额
502 / 503 排查
- 稍后重试
- 在 使用日志 查看
error_message与status_code - 尝试更换模型或联系平台支持
日志与调试
Console 提供 使用日志，可按时间、令牌筛选，查看每次请求的：
- 模型、端点、状态码
- Token 用量与费用
- 延迟与错误信息
建议保存 request_id（若响应中包含）以便 support 排查。
OpenAI SDK 中的错误
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="...", api_key="...")
try:
client.chat.completions.create(model="gpt-4o", messages=[...])
except APIStatusError as e:
print(e.status_code, e.message)import OpenAI from "openai";
try {
await client.chat.completions.create({ model: "gpt-4o", messages: [...] });
} catch (error) {
if (error instanceof OpenAI.APIError) {
console.error(error.status, error.message);
}
}