# API v2 エラーと再試行

> GenderAPI v2 Problem Details、検証エラー、レート制限、請求の不確実性を処理します。再試行料金とサポートに連絡するタイミングについて理解します。

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

Last reviewed: 2026-09-25

## エラーと HTTP ステータス コード

アプリケーション エラーには application/problem+json (RFC 9457) が使用されます。 detail の説明テキストではなく、安定したフィールド code および action を使用してエラーを処理します。検証エラーの場合、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 文字 |
| バッチ | API キーを持つアイテム 50 個。 10 (IP トライアル版) |
| アカウントレート | 1 分あたり 120 リクエスト |
| IP レート | 1 分あたり 600 リクエスト |
| 同時操作 | アカウントごとに 2 個。サービス全体で 16 |