Chyby a opakování API v2

Chyby a stavové kódy HTTP

Chyby aplikace používají application/problem+json (RFC 9457). Ošetřete chyby pomocí stabilních polí code a action, nikoli pomocí vysvětlujícího textu v detail. Pro chyby ověření obsahuje errors umístění ukazatele JSON pro dotčená pole. Při kontaktování podpory uveďte request_id. Selhání proxy nebo připojení může vrátit jiné tělo odpovědi; před analýzou JSON zkontrolujte Content-Type.

Následující syntetický příklad 422 ukazuje neplatnou syntaxi e-mailu před fakturací. Veřejný katalog chyb uvádí každý kód, stav, vysvětlení a navrhovanou akci.

{
  "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 verze 2

Opakované pokusy a účtování

Každý požadavek na predikci je nová operace, včetně znovu zaslaného identického požadavku. Pro každou žádost platí běžná kreditní pravidla. Neexistuje žádná ochrana proti duplicitním žádostem, takže se vyhněte automatickým opakováním po ztrátě připojení nebo neznámém výsledku.

Pro odpověď 429 počkejte před odesláním dalšího požadavku na Retry-After. V případě selhání predikce nejprve zkontrolujte code, action a meta.usage.billing_status. V případě billing_reconciliation_required nebo nepotvrzené fakturace kontaktujte před dalším pokusem podporu se request_id.

Částečně úspěšná dávka může vrátit HTTP 200. Zkontrolujte každou položku a po potvrzení fakturace znovu odešlete pouze neúspěšné položky; úspěšné položky budou v případě opětovného odeslání účtovány znovu.

X-Request-ID a meta.request_id identifikují aktuální pokus o HTTP. Přečtěte si /usage pro aktuální zůstatek. HEAD nespustí fakturovatelnou predikci. Předpovědi a odpovědi účtu nelze uložit do mezipaměti.

Klienti by měli tolerovat aditivní pole odpovědí a zachovat hodnoty null, když informace nejsou k dispozici.

Limity požadavků

Zacházejte se HTTP 429 a Retry-After, nikoli za předpokladu, že požadavky budou vždy přijímány u těchto stropů. Kapacita služby je sdílená. Zobrazené hodnoty jsou aktuální výchozí nastavení služby. Mezi odezvy s frekvenčním limitem patří X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (sekundy Unix). Retry-After je zpoždění v sekundách. Tato záhlaví popisují limity požadavků, nikoli zbývající kredity. Dokonce i bezplatné čtení /usage se započítává do rychlostních limitů.