错误
网关返回标准 HTTP 状态码。错误体的格式取决于错误发生在哪一层:认证层统一格式,接口层与所调用的协议保持一致。
错误体格式
json
{
"code": "INVALID_API_KEY",
"message": "Invalid API key"
}json
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Invalid days, allowed range is 1-90"
}
}json
{
"error": {
"type": "not_found_error",
"message": "Images API is not supported for this platform"
}
}上游返回的错误会原样或按协议转换后透传,message 中可能包含上游的说明。
认证层错误码
| HTTP | code | 原因与处理 |
|---|---|---|
| 400 | api_key_in_query_deprecated | Key 放在了 URL 查询参数里。改用请求头,见认证。 |
| 401 | API_KEY_REQUIRED | 没有携带 Key。 |
| 401 | INVALID_API_KEY | Key 不存在或已删除。 |
| 401 | API_KEY_DISABLED | Key 已在控制台被禁用。 |
| 401 | USER_INACTIVE | 账户已停用,联系管理员。 |
| 403 | API_KEY_EXPIRED | Key 已过期,创建新 Key 或调整过期时间。 |
| 403 | INSUFFICIENT_BALANCE | 余额不足,充值后重试。 |
| 403 | SUBSCRIPTION_NOT_FOUND | 订阅分组下没有有效订阅。 |
| 403 | GROUP_NOT_ALLOWED | Key 所属的专属分组已不再对你开放。 |
| 429 | INVALID_AUTH_RATE_LIMITED | 短时间内多次使用无效 Key,稍后再试。 |
| 503 | API_KEY_AUTH_OVERLOADED | 认证服务暂时繁忙,可以重试。 |
接口层常见错误
| HTTP | error.type | 原因与处理 |
|---|---|---|
| 400 | invalid_request_error | 请求参数不合法,按 message 修正。 |
| 403 | insufficient_quota | OpenAI 协议下的额度不足。 |
| 404 | not_found_error | 当前分组平台不支持该端点,见协议与 Base URL。 |
| 429 | rate_limit_error | 触发上游或网关限速。 |
| 5xx | api_error | 上游暂时不可用。 |
重试建议
- 可以重试:
429、500、502、503、529。使用指数退避,例如 1s、2s、4s,最多 3–5 次。 - 不要重试:
400、401、403、404。这些错误重试不会成功,需要先修正请求或账户状态。 - 异步任务的提交请求不要自动重试,以免重复创建付费任务;先用任务 ID 查询状态。
排查时请提供
联系支持时附上请求时间、使用的端点、模型 ID 和响应中的完整错误体。请勿发送完整的 API Key。