DOCS

错误处理

HTTP 状态、统一错误结构与处理建议。

统一错误结构

JSON
{
  "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错误码处理建议
400BAD_REQUEST检查参数组合。
401MISSING_API_KEY在请求头添加 X-API-Key。
401INVALID_API_KEY检查 key 是否有效、已停用或已过期。
404NOT_FOUND检查路径和资源 ID。
405METHOD_NOT_ALLOWED对外数据接口使用 GET。
422VALIDATION_ERROR根据 details 中的字段提示修正参数。
429RATE_LIMITED按 Retry-After 响应头给出的秒数等待,再重试。
500INTERNAL_ERROR稍后重试;持续出现时联系接入人员。
503SERVICE_BUSY服务暂时繁忙,稍后重试。

处理错误时同时记录 HTTP 状态和业务错误码;日志中不要写入 API key。