错误处理
HTTP 状态、统一错误结构与处理建议。
统一错误结构
{
"error": {
"status": 422,
"code": "VALIDATION_ERROR",
"message": "请求参数不合法",
"details": [
{
"field": "query.limit",
"message": "Input should be less than or equal to 200",
"type": "less_than_equal"
}
]
}
}状态码与处理建议
| HTTP | 错误码 | 处理建议 |
|---|---|---|
| 400 | BAD_REQUEST | 检查参数组合。 |
| 401 | MISSING_API_KEY | 在请求头添加 X-API-Key。 |
| 401 | INVALID_API_KEY | 检查 key 是否有效、已停用或已过期。 |
| 404 | NOT_FOUND | 检查路径和资源 ID。 |
| 405 | METHOD_NOT_ALLOWED | 对外数据接口使用 GET。 |
| 422 | VALIDATION_ERROR | 根据 details 中的字段提示修正参数。 |
| 429 | RATE_LIMITED | 按 Retry-After 响应头给出的秒数等待,再重试。 |
| 500 | INTERNAL_ERROR | 稍后重试;持续出现时联系接入人员。 |
| 503 | SERVICE_BUSY | 服务暂时繁忙,稍后重试。 |
处理错误时同时记录 HTTP 状态和业务错误码;日志中不要写入 API key。