错误码说明
PilotAIHub 网关返回的 HTTP 状态码、错误码及处理建议，帮助你快速定位与排查调用问题。
错误响应格式
所有错误响应遵循 OpenAI 兼容格式，包含
error.message、error.type、error.code 三个字段。 响应头携带 X-Request-Id，可用于全链路日志排查。错误响应示例
{
"error": {
"message": "Model not allowed for this key",
"type": "permission_error",
"code": "model_not_allowed",
"param": null
}
}错误码一览
下表按 HTTP 状态码分组列出网关可能返回的所有错误码。遇到错误时，可根据error.code字段定位原因，并参考「处理建议」操作。
400请求格式错误
请求体不符合协议规范，请检查参数与格式。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| invalid_request | 请求体解析失败或必填字段缺失 | 检查 Content-Type、JSON 格式、model/messages 等必填字段是否正确。 |
401认证失败
API Key 无效或缺失，请检查 Authorization 请求头。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| invalid_key | Key 不存在或格式错误 | 确认请求头 Authorization: Bearer sk-p-xxx 中的 Key 正确无误。 |
402额度与计费
账户余额、套餐额度或预算已用尽，需充值或调整预算。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| insufficient_balance | 账户可用余额不足 | 前往控制台「充值订阅」页面充值，余额需大于 0 才可继续调用。 |
| budget_exceeded | Key 或项目月度预算已达上限 | 在控制台调整 Key / 项目的月度预算阈值，或等待下月重置。 |
403权限不足
Key 状态异常、IP 不在白名单或模型无访问权限。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| key_disabled | 该 Key 已被禁用 | 在控制台「API Key」页面重新启用该 Key，或创建新 Key。 |
| key_expired | 该 Key 已过期 | 在控制台编辑 Key 延长有效期，或创建新 Key。 |
| ip_not_allowed | 请求 IP 不在 Key 白名单内 | 在控制台 Key 编辑页添加当前服务器 IP 到 IP 白名单，或清空白名单（不限 IP）。 |
| model_not_allowed | 当前 Key 无权访问该模型 | 在控制台编辑 Key 的「模型范围」添加目标模型，或将模型范围设为全部。 |
404资源不存在
请求的模型或资源不存在，请检查名称拼写。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| model_not_found | 模型不存在 | 检查 model 字段拼写（含大小写）。数据库中模型名区分大小写，请到模型市场复制准确的模型 code。 |
429限流与排队
请求频率或并发超出限制，请降低调用频率后重试。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| rate_limited | RPM / TPM / 并发超限 | 按响应头 Retry-After 等待后重试，采用指数退避策略。如需提高默认限额请联系商务。 |
| queue_timeout | 并发排队超时 | 当前并发已满，请求排队超时。请降低并发或稍后重试。 |
502网关错误
上游协议不支持或返回异常。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| unsupported_protocol | 供应商协议不支持 | 该模型配置的供应商协议暂不被网关支持，请联系管理员。 |
| upstream_error | 上游返回错误 | 供应商侧返回异常，请稍后重试；持续报错请联系管理员排查供应商配置。 |
503服务不可用
上游模型服务暂时不可用。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| provider_unavailable | 模型服务暂不可用 | 供应商侧服务不可用（可能停机维护或过载），请稍后重试或切换其他模型。 |
500内部错误
网关内部异常，请携带 request_id 联系管理员。
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| internal_error | 网关内部错误 | 请记录响应中的 request_id 并联系管理员排查。 |
各协议错误格式
网关兼容多种入站协议，错误响应的 type / status 字段会按协议规范映射：
| 协议 | 错误标识字段 | 示例 |
|---|---|---|
| OpenAI Chat / Responses | error.type | invalid_request_error / permission_error |
| Claude Messages | error.type | authentication_error / not_found_error |
| Gemini | error.status | PERMISSION_DENIED / NOT_FOUND |
排查建议
- 首先查看
error.code定位错误类别。 - 记录响应头
X-Request-Id，便于管理员在日志中检索全链路。 - 429 错误请按
Retry-After头进行指数退避重试。 - 402 错误请先充值再重试；5xx 错误请稍后重试或切换模型。