GenderAPI.io V2: błędy, limity i ponawianie zapytań

Błędy i kody statusu HTTP

Błędy aplikacji używają formatu application/problem+json (RFC 9457). Obsługuj je na podstawie stabilnych pól code i action, a nie tekstu w detail. Przy błędach walidacji pole errors zawiera lokalizacje JSON Pointer wskazujące odpowiednie pola. Kontaktując się z pomocą techniczną, podaj request_id. Błędy połączenia lub serwera proxy mogą zwrócić inną treść; przed analizą JSON sprawdź Content-Type.

Poniższy syntetyczny przykład 422 pokazuje nieprawidłową składnię adresu e-mail wykrytą przed rozliczeniem. Publiczny katalog błędów zawiera wszystkie kody, statusy, wyjaśnienia i sugerowane działania.

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

• Pełny katalog błędów V2

Pola odpowiedzi z błędem

Metadane dostępu, rozliczenia i zapytania

Ponawianie zapytań i rozliczenia

Każde zapytanie o prognozę to nowa operacja, także wtedy, gdy ponownie wysyłasz identyczne zapytanie. Do każdego zapytania stosuje się zwykłe zasady naliczania kredytów. Nie ma ochrony przed zduplikowanymi zapytaniami, więc unikaj automatycznego ponawiania po utracie połączenia lub przy nieznanym wyniku operacji.

Po odpowiedzi 429 odczekaj czas podany w Retry-After, zanim wyślesz kolejne zapytanie. W przypadku nieudanych prognoz najpierw sprawdź code, action i meta.usage.billing_status. W przypadku billing_reconciliation_required lub niepotwierdzonego rozliczenia (unconfirmed) skontaktuj się z pomocą techniczną, podając request_id, zanim ponowisz zapytanie.

Partia zakończona częściowym powodzeniem może zwrócić HTTP 200. Sprawdź każdy element i po potwierdzeniu rozliczenia prześlij ponownie tylko nieudane elementy; ponownie przesłane udane elementy zostałyby rozliczone jeszcze raz.

X-Request-ID i meta.request_id identyfikują bieżącą próbę HTTP. Aktualne saldo odczytasz w /usage. HEAD nie uruchamia płatnej prognozy. Odpowiedzi z prognozami i danymi konta nie mogą być buforowane.

Aplikacje klienckie powinny tolerować nowe, dodatkowe pola odpowiedzi i zachowywać wartości null, gdy informacje są niedostępne.

Limity zapytań

Obsługuj HTTP 429 i Retry-After, zamiast zakładać, że zapytania zawsze będą akceptowane aż do tych progów. Przepustowość usługi jest współdzielona. Podane wartości to bieżące ustawienia domyślne usługi. Odpowiedzi związane z limitem częstotliwości zapytań zawierają X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (sekundy uniksowe). Retry-After to opóźnienie w sekundach. Te nagłówki opisują limity zapytań, a nie pozostałe kredyty. Nawet bezpłatny odczyt /usage wlicza się do limitów częstotliwości zapytań.