GenderAPI.io V2: Fehler, Limits und Wiederholungen

Fehler und HTTP-Statuscodes

Anwendungsfehler verwenden application/problem+json (RFC 9457). Werten Sie die stabilen Felder code und action aus, nicht den menschenlesbaren Text in detail. Bei Validierungsfehlern enthält errors die JSON-Pointer der betroffenen Stellen. Geben Sie bei Anfragen an den Support die request_id an. Bei Proxy- oder Übertragungsfehlern kann der Antwortinhalt abweichen; prüfen Sie daher Content-Type, bevor Sie JSON parsen.

Das folgende synthetische 422-Beispiel zeigt eine ungültige E-Mail-Syntax vor der Abrechnung. Der öffentliche Fehlerkatalog führt alle Codes, Status, Erklärungen und empfohlenen Maßnahmen auf.

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

• Vollständiger V2-Fehlerkatalog

Felder der Fehlerantwort

Zugang, Abrechnung und Anfragemetadaten

Wiederholungen und Abrechnung

Jede Vorhersageanfrage ist ein neuer Vorgang, auch eine identische, erneut gesendete Anfrage. Für jede Anfrage gelten die normalen Credit-Regeln. Es gibt keinen Schutz vor doppelten Anfragen; vermeiden Sie daher automatische Wiederholungen nach einem Verbindungsabbruch oder einem ungeklärten Ausgang.

Warten Sie bei einer 429-Antwort die Zeit aus Retry-After ab, bevor Sie eine weitere Anfrage senden. Prüfen Sie bei fehlgeschlagenen Vorhersagen zuerst code, action und meta.usage.billing_status. Wenden Sie sich bei billing_reconciliation_required oder unbestätigter Abrechnung mit der request_id an den Support, bevor Sie die Anfrage wiederholen.

Ein teilweise erfolgreicher Batch kann HTTP 200 liefern. Prüfen Sie jeden Eintrag und senden Sie nach bestätigter Abrechnung nur die fehlgeschlagenen Einträge erneut; erneut gesendete erfolgreiche Einträge würden noch einmal berechnet.

X-Request-ID und meta.request_id kennzeichnen den aktuellen HTTP-Versuch. Lesen Sie das aktuelle Guthaben über /usage. HEAD startet keine kostenpflichtige Vorhersage. Vorhersage- und Kontoantworten sind nicht cachebar.

Clients sollten zusätzliche Antwortfelder tolerieren und null-Werte beibehalten, wenn Informationen nicht verfügbar sind.

Anfragelimits

Behandeln Sie HTTP 429 und Retry-After, statt davon auszugehen, dass Anfragen bis zu diesen Obergrenzen immer angenommen werden. Die Kapazität des Dienstes wird geteilt. Die angegebenen Werte sind die aktuellen Standardwerte des Dienstes. Antworten zur Ratenbegrenzung enthalten X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Sekunden). Retry-After ist eine Wartezeit in Sekunden. Diese Header beschreiben Anfragelimits, nicht verbleibende Credits. Auch die kostenlose Abfrage von /usage zählt zu den Anfragelimits.