API v2 エラーと再試行

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

アプリケーション エラーには application/problem+json (RFC 9457) が使用されます。 detail の説明テキストではなく、安定したフィールド code および action を使用してエラーを処理します。検証エラーの場合、errors には、影響を受けるフィールドの JSON ポインターの場所が含まれます。サポートに連絡する場合は、request_id を含めてください。プロキシまたは接続が失敗すると、別の応答本文が返される場合があります。 JSON を解析する前に Content-Type を確認してください。

次の合成 422 の例は、請求前の無効な電子メール構文を示しています。公開エラー カタログには、すべてのコード、ステータス、説明、推奨されるアクションがリストされています。

{
  "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 読み取りでもレート制限の対象となります。