API v2 fejl og genforsøg

Fejl og HTTP statuskoder

Applikationsfejl bruger application/problem+json (RFC 9457). Håndter fejl ved at bruge de stabile felter code og action i stedet for den forklarende tekst i detail. For valideringsfejl indeholder errors JSON Pointer-placeringer for de berørte felter. Inkluder request_id, når du kontakter support. Proxy- eller forbindelsesfejl kan returnere en anden svartekst; tjek Content-Type før parsing af JSON.

Det følgende syntetiske 422-eksempel viser ugyldig e-mail-syntaks før fakturering. Det offentlige fejlkatalog viser hver kode, status, forklaring og foreslået 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
    }
  }
}

• Fuld v2 fejlkatalog

Forsøg igen og fakturering

Hver forudsigelsesanmodning er en ny operation, inklusive en identisk anmodning sendt igen. Normale kreditregler gælder for hver anmodning. Der er ingen duplikat-anmodningsbeskyttelse, så undgå automatiske genforsøg efter et forbindelsestab eller et ukendt resultat.

For et 429-svar skal du vente på Retry-After, før du sender endnu en anmodning. For forudsigelsesfejl skal du først inspicere code, action og meta.usage.billing_status. For billing_reconciliation_required eller ubekræftet fakturering skal du kontakte support med request_id, før du prøver igen.

En delvis vellykket batch kan returnere HTTP 200. Kontroller hver vare og genindsend kun mislykkede varer, efter at faktureringen er bekræftet; vellykkede varer vil blive faktureret igen, hvis de indsendes igen.

X-Request-ID og meta.request_id identificerer det aktuelle HTTP-forsøg. Læs /usage for den aktuelle saldo. HEAD starter ikke en fakturerbar forudsigelse. Forudsigelse og kontosvar kan ikke cachelagres.

Klienter bør tolerere additive responsfelter og bevare null-værdier, når information ikke er tilgængelig.

Anmodningsgrænser

Håndter HTTP 429 og Retry-After i stedet for at antage, at anmodninger altid vil blive accepteret ved disse lofter. Servicekapacitet er delt. De viste værdier er de aktuelle servicestandarder. Rate-limit svar inkluderer X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset (Unix sekunder). Retry-After er en forsinkelse i sekunder. Disse overskrifter beskriver anmodningsgrænser, ikke resterende kreditter. Selv den gratis /usage-læsning tæller med i hastighedsgrænserne.