GenderAPI.io V2: feil og nye forsøk

Feil og HTTP-statuskoder

Applikasjonsfeil bruker application/problem+json (RFC 9457). Bygg logikken på de stabile feltene code og action, ikke på den lesbare teksten i detail. Valideringsfeil inneholder plasseringer som JSON Pointer i errors. Oppgi request_id når du kontakter kundestøtte. Feil i proxy eller transport kan returnere et annet innhold, så sjekk Content-Type før du tolker JSON.

Det syntetiske 422-eksemplet nedenfor viser ugyldig e-postsyntaks før belastning. Den offentlige feilkatalogen viser hver kode, status, forklaring og anbefalt handling.

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

• Fullstendig feilkatalog for V2

Felt i feilsvaret

Metadata om tilgang, belastning og forespørsel

Nye forsøk og belastning

Hver prediksjonsforespørsel er en ny operasjon, også en identisk forespørsel som sendes på nytt. De vanlige kredittreglene gjelder for hver forespørsel. Det finnes ingen beskyttelse mot dupliserte forespørsler, så unngå automatiske nye forsøk etter brudd i tilkoblingen eller et ukjent utfall.

Ved et 429-svar venter du i tiden som er angitt i Retry-After, før du sender en ny forespørsel. Ved feil i prediksjoner sjekker du først code, action og meta.usage.billing_status. Ved billing_reconciliation_required eller ubekreftet belastning kontakter du kundestøtte med request_id før du prøver på nytt.

En delvis vellykket samleforespørsel kan returnere HTTP 200. Kontroller hvert element, og send bare de mislykkede elementene på nytt etter at belastningen er bekreftet; vellykkede elementer blir belastet igjen hvis de sendes på nytt.

X-Request-ID og meta.request_id identifiserer det gjeldende HTTP-forsøket. Les /usage for gjeldende saldo. HEAD starter ikke en prediksjon som belastes. Svar på prediksjoner og kontoforespørsler kan ikke bufres.

Klienter bør tåle nye felt i svaret og beholde null-verdier når informasjon ikke er tilgjengelig.

Forespørselsgrenser

Håndter HTTP 429 og Retry-After i stedet for å anta at forespørsler alltid godtas opp til disse grensene. Tjenestekapasiteten er delt. Verdiene som vises, er gjeldende standardverdier for tjenesten. Svar når en forespørselsgrense er nådd, inneholder X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset (Unix-sekunder). Retry-After er en ventetid i sekunder. Disse headerne beskriver forespørselsgrenser, ikke gjenværende kreditter. Også den gratis avlesningen via /usage teller mot forespørselsgrensene.