# API v2 错误和重试

> 处理 GenderAPI v2 Problem Details、验证错误、速率限制和计费不确定性。了解重试费用以及何时联系支持人员。

Canonical HTML: https://www.genderapi.io/zh/docs/v2/errors-and-retries

Last reviewed: 2026-09-25

## 错误和 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。 |

```json
{
  "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 错误目录](https://api.genderapi.io/api/v2/errors)

## 重试和计费

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

对于 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个全服务 |