错误响应格式
{
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Maximum 200 requests per minute.",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"docs_url": "https://openapi-doc.chuhaijiang.com/errors/RATE_LIMITED"
}
客户端错误（4xx）
| HTTP | code | 说明 | 处理建议 |
|---|
| 400 | BAD_REQUEST | 请求参数无效 | 检查请求参数格式和取值范围 |
| 400 | INVALID_PARAM | 参数值不合法 | 参见 message 中的具体字段提示 |
| 400 | MISSING_PARAM | 缺少必填参数 | 补充 message 中提示的必填字段 |
| 400 | INVALID_SORT_FIELD | 排序字段不合法 | 检查 sort 参数是否为支持的字段 |
| 400 | INVALID_INCLUDE | include 参数不合法 | 检查 include 参数是否为支持的子资源 |
| 400 | PAGE_SIZE_EXCEEDED | 分页大小超限 | 减小 page_size 参数值 |
| 401 | AUTH_MISSING_KEY | 缺少 API Key | 添加 X-API-Key 或 Authorization: Bearer sk_... |
| 401 | AUTH_INVALID_KEY | API Key 无效 | 检查 Key 是否以 sk_live_ 开头 |
| 401 | AUTH_KEY_REVOKED | API Key 已吊销 | 使用新的 API Key |
| 401 | AUTH_KEY_SUSPENDED | API Key 已暂停 | 联系管理员解除暂停 |
| 402 | INSUFFICIENT_BALANCE | 余额不足 | 充值后重试 |
| 403 | FORBIDDEN_SCOPE | 无权限 | 确认 API Key 的权限范围 |
| 404 | ROUTE_NOT_FOUND | 接口不存在 | 检查请求路径 |
| 404 | TASK_NOT_FOUND | 异步任务不存在 | 检查 task_id 是否正确 |
| 429 | RATE_LIMITED | 频率超限 | 降低调用频率，参考 Retry-After 响应头 |
| 429 | QUOTA_EXCEEDED | 配额超限 | 等待配额重置或升级套餐 |
服务端错误（5xx）
| HTTP | code | 说明 | 处理建议 |
|---|
| 500 | INTERNAL_ERROR | 服务内部错误 | 携带 request_id 联系技术支持 |
| 502 | BACKEND_ERROR | 后端服务错误 | 稍后重试 |
| 503 | BACKEND_UNAVAILABLE | 后端不可用 | 稍后重试 |
| 504 | BACKEND_TIMEOUT | 后端超时 | 稍后重试 |
限流响应头
| Header | 说明 | 何时返回 |
|---|
X-RateLimit-Limit | 当前窗口最大请求数 | 所有请求 |
X-RateLimit-Remaining | 剩余请求数 | 仅 429 时（值为 0） |
Retry-After | 建议等待秒数 | 仅 429 时 |
Last modified on
