API V2 的错误与重试

错误与 HTTP 状态码

应用错误使用 application/problem+json（RFC 9457）。请根据稳定的 code 和 action 进行分支处理，而不是依据供人阅读的 detail。验证错误会在 errors 中包含 JSON Pointer 位置。联系支持团队时请附上 request_id。代理或传输故障可能返回不同的响应体，因此解析 JSON 之前请先检查 Content-Type。

下面的合成 422 示例展示了计费前出现的电子邮箱地址语法错误。公开的错误目录列出了每个 code、状态、说明和建议的操作。

{
  "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
    }
  }
}

• 完整的 V2 错误目录

错误响应字段

访问、计费与请求元数据

重试与计费

每个预测请求都是一次新操作，再次发送相同的请求也是如此。每个请求都适用正常的积分规则。系统没有重复请求保护，因此在连接中断或结果未知时，请避免自动重试。

收到 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 读取，也会计入速率限制。