API v2-fouten en nieuwe pogingen

Fouten en HTTP-statuscodes

Applicatiefouten gebruiken application/problem+json (RFC 9457). Behandel fouten met behulp van de stabiele velden code en action, in plaats van de verklarende tekst in detail. Voor validatiefouten bevat errors JSON Pointer-locaties voor de betreffende velden. Vermeld request_id wanneer u contact opneemt met de ondersteuning. Proxy- of verbindingsfouten kunnen een andere antwoordtekst retourneren; controleer Content-Type voordat JSON wordt geparseerd.

Het volgende synthetische 422-voorbeeld toont een ongeldige e-mailsyntaxis vóór facturering. De openbare foutencatalogus vermeldt elke code, status, uitleg en voorgestelde actie.

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

• Volledige v2-foutencatalogus

Nieuwe pogingen en facturering

Elk voorspellingsverzoek is een nieuwe bewerking, inclusief een identiek verzoek dat opnieuw wordt verzonden. Op elke aanvraag zijn de normale kredietregels van toepassing. Er is geen bescherming tegen dubbele verzoeken, dus vermijd automatische nieuwe pogingen na een verbindingsverlies of een onbekende uitkomst.

Wacht voor een 429-antwoord op Retry-After voordat u een nieuw verzoek verzendt. Inspecteer eerst code, action en meta.usage.billing_status voor voorspellingsfouten. Neem voor billing_reconciliation_required of onbevestigde facturering contact op met de ondersteuning van request_id voordat u het opnieuw probeert.

Een gedeeltelijk succesvolle batch retourneert mogelijk HTTP 200. Controleer elk item en dien alleen mislukte items opnieuw in nadat de facturering is bevestigd; succesvolle items worden opnieuw gefactureerd als ze opnieuw worden ingediend.

X-Request-ID en meta.request_id identificeren de huidige HTTP-poging. Lees /usage voor het actuele saldo. HEAD start geen factureerbare voorspelling. Voorspellingen en accountreacties kunnen niet in de cache worden opgeslagen.

Klanten moeten additieve responsvelden tolereren en de null-waarden behouden wanneer informatie niet beschikbaar is.

Verzoeklimieten

Ga om met HTTP 429 en Retry-After in plaats van ervan uit te gaan dat verzoeken altijd bij deze plafonds worden geaccepteerd. De servicecapaciteit wordt gedeeld. De weergegeven waarden zijn de huidige servicestandaarden. Snelheidslimietreacties omvatten X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (Unix-seconden). Retry-After is een vertraging in seconden. Deze headers beschrijven verzoeklimieten, niet de resterende tegoeden. Zelfs de gratis /usage-uitlezing telt mee voor de tarieflimieten.