API v2 feil og forsøk på nytt

Feil og HTTP statuskoder

Applikasjonsfeil bruker application/problem+json (RFC 9457). Håndter feil ved å bruke de stabile feltene code og action, i stedet for den forklarende teksten i detail. For valideringsfeil inneholder errors JSON-pekerplasseringer for de berørte feltene. Inkluder request_id når du kontakter support. Proxy- eller tilkoblingsfeil kan returnere en annen svartekst; sjekk Content-Type før du analyserer JSON.

Følgende syntetiske 422-eksempel viser ugyldig e-postsyntaks før fakturering. Den offentlige feilkatalogen viser hver kode, status, forklaring og foreslåtte 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
    }
  }
}

• Full v2 feilkatalog

Forsøk på nytt og fakturering

Hver prediksjonsforespørsel er en ny operasjon, inkludert en identisk forespørsel sendt på nytt. Vanlige kredittregler gjelder for hver forespørsel. Det er ingen beskyttelse mot duplikatforespørsel, så unngå automatiske gjenforsøk etter et tilkoblingstap eller et ukjent utfall.

For et 429-svar, vent på Retry-After før du sender en ny forespørsel. For prediksjonsfeil, inspiser code, action og meta.usage.billing_status først. For billing_reconciliation_required eller ubekreftet fakturering, kontakt support med request_id før du prøver på nytt.

En delvis vellykket batch kan returnere HTTP 200. Sjekk hver vare og send inn kun mislykkede varer på nytt etter at faktureringen er bekreftet; vellykkede varer vil bli fakturert på nytt hvis de sendes inn på nytt.

X-Request-ID og meta.request_id identifiserer gjeldende HTTP-forsøk. Les /usage for gjeldende saldo. HEAD starter ikke en fakturerbar prediksjon. Forslag og kontosvar kan ikke bufres.

Klienter bør tolerere additive responsfelter og bevare null-verdier når informasjon er utilgjengelig.

Forespørselsgrenser

Håndter HTTP 429 og Retry-After i stedet for å anta at forespørsler alltid vil bli akseptert ved disse tak. Tjenestekapasitet er delt. Verdiene som vises er gjeldende tjenestestandarder. Frekvensgrensesvar inkluderer X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset (Unix sekunder). Retry-After er en forsinkelse i sekunder. Disse overskriftene beskriver forespørselsgrenser, ikke gjenværende kreditter. Selv den gratis /usage-avlesningen teller mot satsgrensene.