Błędy i ponowne próby API v2

Błędy i kody stanu 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ę wiadomości e-mail przed rozliczeniem. Publiczny katalog błędów zawiera listę wszystkich kodów, statusów, wyjaśnień i sugerowanych działań.

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

Ponowne próby i rozliczenia

Każde żądanie predykcji to nowa operacja, w tym także ponowne wysłanie identycznego żądania. Do każdego wniosku mają zastosowanie normalne zasady kredytowania. Nie ma ochrony przed duplikatami żądań, więc unikaj automatycznych ponownych prób w przypadku utraty połączenia lub nieznanego wyniku.

Aby uzyskać odpowiedź 429, poczekaj na Retry-After przed wysłaniem kolejnego żądania. W przypadku niepowodzeń przewidywania najpierw sprawdź code, action i meta.usage.billing_status. W przypadku billing_reconciliation_required lub niepotwierdzonych rozliczeń skontaktuj się z pomocą techniczną pod adresem request_id przed ponowną próbą.

Częściowo udana partia może zwrócić HTTP 200. Sprawdź każdą pozycję i prześlij ponownie tylko pozycje, które się nie powiodły, po potwierdzeniu rozliczenia; pomyślne pozycje zostaną ponownie naliczone w przypadku ponownego przesłania.

X-Request-ID i meta.request_id identyfikują bieżącą próbę HTTP. Przeczytaj /usage, aby uzyskać aktualne saldo. HEAD nie uruchamia prognozy rozliczania. Prognozy i odpowiedzi konta nie są buforowane.

Klienci powinni tolerować addytywne pola odpowiedzi i zachowywać wartości null, gdy informacje są niedostępne.

Limity żądań

Zajmij się HTTP 429 i Retry-After, zamiast zakładać, że żądania będą zawsze akceptowane na tych sufitach. Pojemność usług jest współdzielona. Wyświetlane wartości są bieżącymi ustawieniami domyślnymi usługi. Odpowiedzi dotyczące limitów szybkości obejmują X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (sekundy Unix). Retry-After to opóźnienie w sekundach. Te nagłówki opisują limity żądań, a nie pozostałe kredyty. Nawet bezpłatny odczyt /usage wlicza się do limitów szybkości.