API v2 Fehler und Wiederholungsversuche

Fehler und HTTP-Statuscodes

Anwendungsfehler verwenden application/problem+json (RFC 9457). Werten Sie die stabilen Felder code und action aus, nicht den Erklärungstext in detail. Bei Validierungsfehlern enthält errors die JSON-Pointer der betroffenen Felder. Geben Sie dem Support die request_id an. Bei Proxy- oder Verbindungsfehlern kann der Antwortinhalt abweichen; prüfen Sie Content-Type vor dem Einlesen als JSON.

Das folgende synthetische 422-Beispiel zeigt eine ungültige E-Mail-Syntax vor der Abrechnung. Der öffentliche Fehlerkatalog listet alle Codes, Status, Erklärungen und vorgeschlagenen 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

Wiederholungsversuche und Abrechnung

Jede Vorhersageanfrage ist ein neuer Vorgang, einschließlich einer erneut gesendeten identischen Anfrage. Für jede Anfrage gelten die normalen Kreditregeln. Es gibt keinen Schutz vor doppelten Anfragen. Vermeiden Sie daher automatische Wiederholungsversuche nach einem Verbindungsverlust oder einem unbekannten Ergebnis.

Warten Sie bei einer 429-Antwort auf Retry-After, bevor Sie eine weitere Anfrage senden. Überprüfen Sie bei Vorhersagefehlern zunächst code, action und meta.usage.billing_status. Wenden Sie sich bei billing_reconciliation_required oder unbestätigter Abrechnung an den Support mit request_id, bevor Sie es erneut versuchen.

Ein teilweise erfolgreicher Stapel gibt möglicherweise HTTP 200 zurück. Überprüfen Sie jeden Artikel und reichen Sie nur fehlerhafte Artikel erneut ein, nachdem die Abrechnung bestätigt wurde. Erfolgreiche Artikel würden bei erneuter Übermittlung erneut in Rechnung gestellt.

X-Request-ID und meta.request_id identifizieren den aktuellen HTTP-Versuch. Lesen Sie /usage für den aktuellen Kontostand. HEAD startet keine abrechenbare Vorhersage. Vorhersagen und Kontoantworten können nicht zwischengespeichert werden.

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

Anforderungslimits

Behandeln Sie HTTP 429 und Retry-After, anstatt davon auszugehen, dass Anfragen bei diesen Obergrenzen immer akzeptiert werden. Die Servicekapazität wird geteilt. Die angezeigten Werte sind die aktuellen Dienststandards. Zu den Ratenbegrenzungsantworten gehören X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Sekunden). Retry-After ist eine Verzögerung in Sekunden. Diese Header beschreiben Anforderungslimits, nicht verbleibende Credits. Sogar der kostenlose /usage-Lesevorgang wird auf die Ratenbegrenzung angerechnet.