文档/错误处理

错误处理

所有 API 错误都采用统一格式。以下是妥善处理错误的方法。

查看 Markdown OpenAPI JSON

错误响应格式

发生错误时，API 会返回如下结构的 JSON 对象：

json
{
  "error": "Validation Error",
  "message": "The email field is required.",
  "status_code": 422
}

错误代码

状态码错误原因与解决方法
400 请求错误（Bad Request） JSON 格式错误或缺少必填字段。请检查请求体。
401 未授权（Unauthorized） API 密钥缺失或无效。请检查Authorization请求头。
402 需要付费（Payment Required） 积分不足。请购买更多积分，或等待每日限额重置。
422 验证错误（Validation Error） 邮箱地址格式无效。请检查发送的值。
429 请求过多（Too Many Requests） 超出速率限制。请查看Retry-After请求头并等待。
500 服务器内部错误（Internal Server Error） 我们这边出了点问题。请几秒后重试。联系支持团队（若持续失败）。

401 Unauthorized（未授权）

json
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status_code": 401
}

解决方法：请确认您的Authorization请求头格式正确，应为Bearer YOUR_API_KEY。并在控制台中核对密钥。

422 Validation Error（验证错误）

json
{
  "error": "Validation Error",
  "message": "The email field must be a valid email address.",
  "status_code": 422
}

解决方法：确保 email 值是有效的邮箱格式（例如user@example.com）。发送前先清理输入。

429 Too Many Requests（请求过多）

json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please slow down.",
  "status_code": 429,
  "retry_after": 15
}

解决方法：请等待retry_after中指定的秒数后再重试。参见速率限制 →

故障排查清单