错误码
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
}
}常见状态码
| 状态码 | 类型 / code | 含义与处理 |
|---|---|---|
| 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 | daily_limit_exceeded / monthly_limit_exceeded | Key 的已提交消费达到日限额或月限额。按 Retry-After 等到对应的 Asia/Shanghai 窗口重置。 |
| 429 | rate_limit_error / glm_tpm_capacity / provider code | 通用、模型或上游速率限制。优先遵循上游 Retry-After；缺少该响应头时，仅对幂等或可安全重试的请求做指数退避，避免盲目重试。 |
| 500 | internal_error | OneGate 内部错误。请直接重试，或联系支持。 |
| 503 | quota_check_failed | 额度查询发生数据库错误时失败关闭，并返回 503；不会访问上游。 |
| 503 | billing_unavailable | 非流式请求的计费写入失败。请求不应盲目重试；请先确认请求结果再按幂等策略处理。 |
| 502 / 503 | upstream_error | 上游错误会按现有接口契约透传或返回。聊天不会自动切换 provider；每个 GLM 请求固定使用开始时解析出的上游，resolved Tencent GLM 绝不会 fallback 到 Tokaify。 |
| 503 | glm_routing_unavailable / provider_not_ready | 逐模型 GLM 路由配置或目标 provider 暂不可用。请求失败关闭且不会访问备用上游；请稍后安全重试或联系支持。 |
重试策略建议
429 优先遵循 Retry-After；上游 500 / 502 / 503 可按业务幂等性指数退避。quota_check_failed 与 billing_unavailable 不应盲目重试。其他 4xx 请先修正请求。