How should a client handle 429?

Reduce request frequency, apply exponential backoff, and review quota and usage instead of immediately repeating the same request at high frequency.

How should a client handle 500?

Record the response and request id when present, retry later, and provide non-secret error details to support if the problem continues.

Error-handling summary

EasyAPI uses HTTP status codes for error categories and can return message, type, and code in an error object. A client should fix the request, check credentials, back off, or contact support according to the status.

Key facts

400 means request parameters are invalid or a required field is missing.
401 means the API key is missing or invalid.
429 means a rate or quota limit was reached, while 500 means an internal server error.

API error FAQ

How should a client handle 429?: Reduce request frequency, apply exponential backoff, and review quota and usage instead of immediately repeating the same request at high frequency.
How should a client handle 500?: Record the response and request id when present, retry later, and provide non-secret error details to support if the problem continues.

错误码与状态码

HTTP 状态码与业务错误码对照。

错误码与状态码

API 错误以 HTTP 状态码表示类别，响应体中可包含 error 对象（含 message、type、code 等字段，与 OpenAI 风格兼容）。

常见错误

HTTP 状态码	错误码	描述
`400`	`invalid_request_error`	请求参数无效或缺失必填字段
`401`	`invalid_api_key`	未提供或无效的 API Key
`429`	`rate_limit_exceeded`	请求频率或配额超限
`500`	`server_error`	服务端内部错误，请稍后重试

错误响应示例

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

处理建议

401：检查 Authorization 头与 Key 是否有效
429：实施指数退避重试，或升级配额
500：记录 request id（若有）并联系支持