Gengxi API Developer Docs
错误
理解公开错误码并采取安全的恢复操作。
错误处理
可使用 HTTP 状态、稳定的公开错误码、message 和 Request ID。不要将内部 provider 细节当作稳定契约。
错误参考
| 状态 | 代码 | 含义 | 处理方式 |
|---|---|---|---|
| 400 | invalid_request_error | 请求格式错误或不支持 | 检查字段和 Content-Type |
| 400 | api_key_in_query_deprecated | 使用了 Query 验证 | 将 Key 移至 Header |
| 401 | API_KEY_REQUIRED / INVALID_API_KEY | 缺少或无效 Key | 检查 Header 和 Key |
| 401 | API_KEY_DISABLED / USER_INACTIVE | Key 已禁用或用户不可用 | 检查账户与 Key 状态 |
| 403 | API_KEY_EXPIRED | Key 已过期 | 创建或更新有效 Key |
| 403 | INSUFFICIENT_BALANCE / ACCESS_DENIED | 余额或访问策略拦截 | 检查 Usage、订阅和分组 |
| 404 | model_not_found / not_found_error | 模型或资源不可用 | 请求 GET /v1/models 并检查路径 |
| 429 | API_KEY_QUOTA_EXHAUSTED / USAGE_LIMIT_EXCEEDED / rate_limit_exceeded | 达到配额或速率限制 | 遵循 Retry-After 并指数退避 |
| 500 | INTERNAL_ERROR | 内部错误 | 安全重试；携 Request ID 联系客服 |
| 502 | upstream_error | 上游请求失败 | 稍后退避重试 |
| 503 | service_unavailable / API_KEY_AUTH_OVERLOADED | 暂时容量不足 | 稍后退避重试 |
重试策略
- 只重试幂等或可安全重复的操作。
- 429 应遵循 Retry-After。
- 429、502 和 503 使用带抖动的指数退避。
- 持续 500 时携 Request ID 联系客服。