API v2 错误和重试

错误和 HTTP 状态代码

应用程序错误使用 application/problem+json (RFC 9457)。使用稳定字段 code 和 action 处理错误，而不是使用 detail 中的说明文本。对于验证错误，errors 包含受影响字段的 JSON 指针位置。联系支持人员时请注明 request_id。代理或连接失败可能会返回不同的响应正文；在解析 JSON 之前检查 Content-Type。

以下合成 422 示例显示了计费前的无效电子邮件语法。公共错误目录列出了每个代码、状态、解释和建议的操作。

HTTP 状态	典型含义	下一步
400 / 413 / 415	JSON 格式错误、主体过大或不受支持的介质类型。	更正请求。
401 / 403	访问被拒绝、账户限制或积分不足。	检查code；正确访问或补充积分/等待试用重置。
422	输入无效或选项不兼容。	更正 errors 中标识的字段。
404 / 405	未知路由或不支持的 HTTP 方法。	检查端点路径和 Allow 响应标头。
429	速率或并发限制。	在发送另一个请求之前等待 Retry-After。
500	服务器意外故障。	联系支持人员 request_id；重试之前请检查帐单。
502 / 503 / 504	提供商、依赖性、计费或超时失败。	重试前检查 code、action 和 billing_status。

{
  "type": "urn:genderapi:problem:validation_error",
  "title": "validation error",
  "status": 422,
  "detail": "A valid email address is required.",
  "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
  "code": "validation_error",
  "request_id": "11111111-1111-4111-8111-111111111111",
  "documentation": "https://api.genderapi.io/api/v2/errors",
  "action": "correct_request",
  "errors": [
    {
      "pointer": "/value",
      "message": "Invalid email address."
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 0,
      "remaining_credits": null,
      "billing_status": "not_charged",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

重试和计费

每个预测请求都是一个新的操作，包括再次发送的相同请求。正常信用规则适用于每个请求。没有重复请求保护，因此请避免在连接丢失或未知结果后自动重试。

对于 429 响应，请等待 Retry-After，然后再发送另一个请求。对于预测失败，请首先检查 code、action 和 meta.usage.billing_status。对于 billing_reconciliation_required 或未确认的计费，请在重试之前联系 request_id 支持人员。

部分成功的批次可能会返回 HTTP 200。检查每个项目，并在确认计费后仅重新提交失败的项目；如果重新提交，成功的项目将再次计费。

X-Request-ID 和 meta.request_id 标识当前 HTTP 尝试。读取 /usage 以获取当前余额。 HEAD 不启动计费预测。预测和帐户响应不可缓存。

客户端应容忍附加响应字段并在信息不可用时保留 null 值。

请求限制

处理 HTTP 429 和 Retry-After，而不是假设在这些上限下请求总是被接受。服务能力共享。显示的值是当前服务默认值。速率限制响应包括 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset（Unix 秒）。 Retry-After 是以秒为单位的延迟。这些标头描述请求限制，而不是剩余积分。即使免费的 /usage 读取也会计入速率限制。

限制	值
JSON 请求正文	64 KiB 最大值
预测值	1–254 个字符
批次	50 个带有 API 密钥的物品； 10.用IP试用
账户费率	每分钟 120 个请求
IP 率	每分钟 600 个请求
并发操作	每个帐户 2 个； 16个全服务