# Błędy i ponowne próby API v2

> Obsługa GenderAPI v2 Problem Details, błędy walidacyjne, limity stawek i niepewność rozliczeń. Dowiedz się, jakie są opłaty za ponowną próbę i kiedy należy skontaktować się z pomocą techniczną.

Canonical HTML: https://www.genderapi.io/pl/docs/v2/errors-and-retries

Last reviewed: 2026-09-25

## 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ń.

| Stan HTTP | Typowe znaczenie | Następny krok |
| --- | --- | --- |
| 400 / 413 / 415 | Zniekształcony JSON, zbyt duża obudowa lub nieobsługiwany typ nośnika. | Popraw żądanie. |
| 401 / 403 | Dostęp odrzucony, ograniczenie konta lub niewystarczające środki. | Sprawdź code; popraw dostęp lub uzupełnij kredyty / poczekaj na reset próbny. |
| 422 | Nieprawidłowe dane wejściowe lub niezgodne opcje. | Popraw pola zidentyfikowane w errors. |
| 404 / 405 | Nieznana trasa lub nieobsługiwana metoda HTTP. | Sprawdź ścieżkę punktu końcowego i nagłówek odpowiedzi Allow. |
| 429 | Limit szybkości lub współbieżności. | Poczekaj na Retry-After przed wysłaniem kolejnego żądania. |
| 500 | Nieoczekiwana awaria serwera. | Skontaktuj się z pomocą techniczną za pomocą request_id; sprawdź rozliczenia przed ponowną próbą. |
| 502 / 503 / 504 | Dostawca, zależność, rozliczenie lub błąd przekroczenia limitu czasu. | Sprawdź code, action i billing_status przed ponowną próbą. |

```json
{
  "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](https://api.genderapi.io/api/v2/errors)

## 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.

| Limit | Wartość |
| --- | --- |
| Treść żądania JSON | maksymalnie 64 KiB |
| Wartość przewidywania | 1–254 znaki |
| Partia | 50 szt. z kluczem API; 10 z wersją próbną IP |
| Stawka konta | 120 żądań na minutę |
| Stawka IP | 600 żądań na minutę |
| Jednoczesne operacje | 2 na konto; 16 w całym serwisie |