# Błędy i limity zapytań
Source: https://nordvec.com/pl/docs/guides/errors-and-rate-limits

Jedna struktura błędu zwracana przy każdym nieudanym zapytaniu, nagłówki limitu zapytań oraz jak bezpiecznie ponowić zapis.



Każdy endpoint zwraca błędy w ten sam sposób, więc obsługujesz błędy, limity i ponawianie żądań raz, a następnie używasz tego kodu wszędzie, także przez [MCP](/docs/guides/mcp).

## Struktura odpowiedzi błędu [#struktura-odpowiedzi-błędu]

Każda odpowiedź, która nie jest kodem 2xx, to jeden obiekt JSON:

```json
{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```

* `code` to błąd na poziomie HTTP, na przykład `UNAUTHORIZED`, `FORBIDDEN`,
  `NOT_FOUND`, `BAD_REQUEST` lub `TOO_MANY_REQUESTS`.
* `data.reason`, jeśli występuje, to dokładniejszy, zrozumiały dla maszyny powód, taki jak
  `auth.key_not_found` lub `rate_limit.exceeded`. Rozgałęziaj kod na podstawie tego pola, a nie na podstawie
  `message`, które jest przeznaczone dla ludzi i może się zmienić.
* `defined` to `true`, gdy operacja wymienia ten błąd w
  [dokumentacji API](/docs/api), oraz `false` dla błędów, które może napotkać każde żądanie
  (uwierzytelnianie, limity, nieznana ścieżka).
* Nieudana walidacja zwraca `BAD_REQUEST` z problemami w
  `data.formErrors` i `data.fieldErrors`.

Każda odpowiedź zawiera również `X-Request-ID`. Cytuj go, gdy kontaktujesz się z pomocą techniczną,
a my odnajdziemy dokładnie to żądanie.

## Najczęstsze kody statusów [#najczęstsze-kody-statusów]

| Status | Kod                     | Co zrobić                                                                      |
| ------ | ----------------------- | ------------------------------------------------------------------------------ |
| `400`  | `BAD_REQUEST`           | Popraw żądanie; `data.fieldErrors` wskazuje pola                               |
| `401`  | `UNAUTHORIZED`          | Wyślij poprawny klucz lub sesję                                                |
| `403`  | `FORBIDDEN`             | Klucz nie ma wymaganego zakresu lub roli dla tej operacji                      |
| `404`  | `NOT_FOUND`             | Zasób nie istnieje lub nie masz do niego dostępu                               |
| `409`  | `CONFLICT`              | Duplikowane żądanie zapisu jest w trakcie przetwarzania; ponów próbę za chwilę |
| `413`  | `PAYLOAD_TOO_LARGE`     | Ciało żądania przekracza 1 MB; podziel przesyłanie zbiorcze na mniejsze partie |
| `422`  | `UNPROCESSABLE_CONTENT` | Żądanie jest poprawnie sformułowane, ale nie może zostać zastosowane           |
| `429`  | `TOO_MANY_REQUESTS`     | Poczekaj na `Retry-After`, a następnie ponów próbę                             |

## Limity żądań [#limity-żądań]

Każda odpowiedź zawiera informacje o limicie, względem którego zostało zliczone żądanie, w dwóch formach:

* nagłówki `X-RateLimit-*`;
* strukturalne pola IETF `RateLimit` (aktualny stan: `r` to liczba pozostałych żądań,
  `t` to sekundy do resetu okna) oraz `RateLimit-Policy`
  (kwota: `q` to limit, `w` to okno w sekundach).

Odpowiedź `429` zawiera również `Retry-After` w sekundach oraz `data.retryAfterMs`. Poczekaj co najmniej tyle czasu przed następnym żądaniem; ponowienie próby wcześniej zostanie zliczone i odrzucone ponownie.

## Bezpieczne ponawianie żądań zapisu [#bezpieczne-ponawianie-żądań-zapisu]

Operacja zapisu, która wymienia nagłówek `Idempotency-Key` w
[dokumentacji API](/docs/api), może być ponawiana bez ryzyka podwójnego wykonania. Wyślij jeden klucz na logiczną operację zapisu i powtarzaj ten sam klucz przy każdej próbie ponowienia:

* ten sam klucz z tym samym ciałem w ciągu 24 godzin odtwarza zapisaną odpowiedź;
* ten sam klucz z innym ciałem jest odrzucany z kodem `422`;
* duplikat, który dotrze, gdy pierwsze żądanie jest jeszcze w trakcie przetwarzania, otrzymuje `409`.

Operacja bez tego nagłówka nie jest idempotentna, więc ponawiaj ją tylko wtedy, gdy wiesz, że pierwsza próba nie została zrealizowana.