GenderAPI.io V2: fejl og nye forsøg

Fejl og HTTP-statuskoder

Applikationsfejl bruger application/problem+json (RFC 9457). Styr logikken efter de stabile felter code og action, ikke efter den læsbare tekst i detail. Valideringsfejl indeholder JSON Pointer-placeringer i errors. Angiv request_id, når du kontakter support. Fejl i proxy eller transport kan returnere en anden body, så kontrollér Content-Type, før du parser JSON.

Det følgende syntetiske 422-eksempel viser ugyldig e-mailsyntaks før opkrævning. Det offentlige fejlkatalog viser alle koder, statusser, forklaringer og foreslåede handlinger.

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

• Komplet fejlkatalog for V2

Felter i fejlsvaret

Metadata om adgang, opkrævning og forespørgslen

Nye forsøg og opkrævning

Hver forespørgsel om en forudsigelse er en ny operation, også når en identisk forespørgsel sendes igen. De normale regler for kreditter gælder for hver forespørgsel. Der er ingen beskyttelse mod dubletter, så undgå automatiske nye forsøg efter en afbrudt forbindelse eller et ukendt udfald.

Ved et 429-svar skal du vente den tid, Retry-After angiver, før du sender en ny forespørgsel. Ved fejl i forudsigelser skal du først kontrollere code, action og meta.usage.billing_status. Ved billing_reconciliation_required eller ubekræftet opkrævning skal du kontakte support med request_id, før du prøver igen.

En batch med delvis succes kan returnere HTTP 200. Kontrollér hvert element, og send kun de mislykkede elementer igen, når opkrævningen er bekræftet. Gennemførte elementer ville blive opkrævet igen, hvis de blev sendt igen.

X-Request-ID og meta.request_id identificerer det aktuelle HTTP-forsøg. Læs /usage for at se den aktuelle saldo. HEAD starter ikke en forudsigelse, der koster kreditter. Svar på forudsigelser og kontooplysninger må ikke caches.

Klienter bør tåle nye felter i svaret og bevare null-værdier, når oplysninger ikke er tilgængelige.

Forespørgselsgrænser

Håndtér HTTP 429 og Retry-After i stedet for at gå ud fra, at forespørgsler altid accepteres op til disse lofter. Tjenestens kapacitet er delt. De viste værdier er tjenestens aktuelle standarder. Svar ved overskredne grænser indeholder X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset (Unix-sekunder). Retry-After er en forsinkelse i sekunder. Disse headers beskriver forespørgselsgrænser, ikke resterende kreditter. Selv den gratis læsning af /usage tæller med i forespørgselsgrænserne.