GenderAPI.io V2: chyby a opakování požadavků

Chyby a stavové kódy HTTP

Chyby aplikace používají application/problem+json (RFC 9457). Rozhodujte se podle stabilních polí code a action, ne podle textu v detail. Chyby validace obsahují v errors umístění ve formátu JSON Pointer. Při kontaktu s podporou uveďte request_id. Selhání proxy nebo přenosu může vrátit jiné tělo, proto před parsováním JSON zkontrolujte Content-Type.

Následující syntetický příklad 422 ukazuje neplatnou syntaxi e-mailu před účtováním. Veřejný katalog chyb uvádí každý kód, stav, vysvětlení a doporučený postup.

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

• Úplný katalog chyb V2

Pole chybové odpovědi

Metadata přístupu, účtování a požadavku

Opakování požadavků a účtování

Každý požadavek na odhad je nová operace, i když znovu posíláte totožný požadavek. Na každý požadavek se vztahují běžná pravidla pro kredity. Ochrana proti duplicitním požadavkům neexistuje, proto se po ztrátě spojení nebo při neznámém výsledku vyhněte automatickému opakování.

U odpovědi 429 počkejte před dalším požadavkem po dobu uvedenou v Retry-After. U selhání odhadu nejprve zkontrolujte code, action a meta.usage.billing_status. U billing_reconciliation_required nebo nepotvrzeného účtování kontaktujte před opakováním podporu a uveďte request_id.

Částečně úspěšná dávka může vrátit HTTP 200. Zkontrolujte každou položku a po potvrzení účtování znovu odešlete jen neúspěšné položky; opětovně odeslané úspěšné položky by se naúčtovaly znovu.

X-Request-ID a meta.request_id identifikují aktuální pokus HTTP. Aktuální zůstatek zjistíte přes /usage. HEAD nespouští zpoplatněný odhad. Odpovědi s odhady a údaji o účtu se neukládají do mezipaměti.

Klienti by měli tolerovat nově přidaná pole odpovědi a zachovávat hodnoty null, když informace nejsou k dispozici.

Limity požadavků

Zpracovávejte HTTP 429 a Retry-After a nepředpokládejte, že požadavky budou při těchto horních mezích vždy přijaty. Kapacita služby je sdílená. Uvedené hodnoty jsou aktuální výchozí nastavení služby. Odpovědi při překročení limitu obsahují X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (sekundy v čase Unix). Retry-After je prodleva v sekundách. Tyto hlavičky popisují limity počtu požadavků, ne zbývající kredity. I bezplatné zjištění zůstatku přes /usage se započítává do limitů počtu požadavků.