API V2のエラーと再試行

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

アプリケーションエラーにはapplication/problem+json（RFC 9457）が使われます。処理の分岐には、人が読むためのdetailではなく、安定したcodeとactionを使ってください。検証エラーでは、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の照会もレート制限の対象です。