错误码
OneGate 返回标准 HTTP 状态码与 OpenAI 兼容的错误体。客户端可以按 status code 与 error.type 处理。
错误结构
json
{
"error": {
"message": "Insufficient balance. Top up at https://onegate.club/console/billing.",
"type": "insufficient_balance",
"code": "billing_balance_low",
"param": null
}
}常见状态码
| 状态码 | 类型 | 含义与处理 |
|---|---|---|
| 400 | invalid_request_error | 请求参数不合法。检查 message 格式、model 名拼写。 |
| 401 | invalid_api_key | API Key 无效或已撤销。 |
| 402 | insufficient_balance | 账户余额不足，前往控制台充值。 |
| 403 | permission_denied | Key 没有权限调用该模型或端点。 |
| 404 | model_not_found | 模型 ID 不存在，请查 /models。 |
| 429 | rate_limit_exceeded | 触发速率限制。建议指数退避重试，从 1s 起翻倍，最多 5 次。 |
| 500 | internal_error | OneGate 内部错误。请直接重试，或联系支持。 |
| 502 / 503 | upstream_unavailable | 上游模型短暂不可用。系统会自动尝试容灾路由。 |
重试策略建议
对 429 / 500 / 502 / 503 使用指数退避；对 4xx（400/401/402/403/404）不要重试，先修业务再发。