> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Błędy

> Format błędów i kody błędów zwracane przez API GetQR.

> [!NOTE]
>
> API GetQR jest w wersji beta i jest dostępne dla wybranych obszarów roboczych. Szczegóły mogą się zmienić przed ogólną premierą.

API GetQR używa standardowych kodów statusu HTTP. Udane żądania zwracają `2xx`. Nieudane żądania zwracają `4xx` lub `5xx` z treścią JSON, która wyjaśnia, co poszło nie tak.

## Format błędu

Każdy błąd ma ten sam kształt: stały kod, czytelny komunikat i link do opisu tego kodu.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

Stały, czytelny maszynowo kod błędu. Używaj go w swoim kodzie zamiast komunikatu. Zobacz [Kody błędów](#kody-błędów).

**error.message** `string` *required*

Czytelny dla człowieka opis problemu. Jego treść może się zmienić.

**error.doc\_url** `string` *required*

Link do opisu kodu błędu w dokumentacji API na Twoim koncie GetQR.

## Kody błędów

| Kod | Status HTTP | Kiedy występuje |
| - | - | - |
| `bad_request` | 400 | Żądanie jest nieprawidłowe: treść nie jest poprawnym JSON-em, nagłówek `Authorization` nie ma prefiksu `Bearer ` albo akcja nie jest dozwolona w obecnym stanie zasobu (np. anulowanie zakończonego masowego tworzenia). |
| `unauthorized` | 401 | Brak klucza API albo klucz jest nieprawidłowy, np. dlatego, że został wygenerowany ponownie. |
| `forbidden` | 403 | Subskrypcja właściciela obszaru roboczego nie jest aktywna albo Twoja rola w obszarze roboczym nie pozwala na tę akcję. |
| `exceeded_limit` | 403 | Osiągnięto limit planu. W planie Single QR: tworzenie lub duplikowanie kodu QR, gdy obszar roboczy ma już jeden kod, albo rozpoczęcie masowego tworzenia. |
| `not_found` | 404 | Zasób nie istnieje lub nie należy do Twojego obszaru roboczego, endpoint nie istnieje albo API nie jest włączone dla Twojego obszaru roboczego. |
| `method_not_allowed` | 405 | Endpoint istnieje, ale nie obsługuje tej metody HTTP. Nagłówek `Allow` podaje metody, które obsługuje. |
| `conflict` | 409 | Żądanie koliduje z istniejącymi danymi: slug krótkiego linku jest zajęty, żądanie z tym samym `Idempotency-Key` wciąż trwa, harmonogram nakłada się na istniejący albo archiwum masowego tworzenia nie jest jeszcze gotowe. |
| `invite_pending` | 409 | Zaproszono Cię do obszaru roboczego, ale jeszcze do niego nie dołączyłeś. Żądania z kluczem API go nie zwracają: obszar roboczy klucza to zawsze taki, do którego należysz. |
| `invite_expired` | 410 | Twoje zaproszenie do obszaru roboczego wygasło. Żądania z kluczem API go nie zwracają, z tego samego powodu. |
| `unprocessable_entity` | 422 | Treść lub parametry zapytania nie przeszły walidacji. Komunikat wskazuje pole i to, co jest z nim nie tak. Zobacz [Błędy walidacji](#błędy-walidacji). |
| `rate_limit_exceeded` | 429 | Klucz API wykorzystał limit żądań w bieżącym oknie. Zobacz [Limity żądań](https://docs.getqr.com/pl/api/rate-limits.md). |
| `internal_server_error` | 500 | Coś poszło nie tak po naszej stronie. Spróbuj ponownie później, a jeśli błąd się powtarza, skontaktuj się z pomocą techniczną. |

## Błędy walidacji

Gdy treść lub parametry zapytania nie przejdą walidacji, API odpowiada `422`. Komunikat opisuje pierwsze nieprawidłowe pole w postaci `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

Pola zagnieżdżone są zapisywane w notacji kropkowej, np. `link.url`.

## Obsługa błędów

* Rozgałęziaj logikę według `error.code`, a nie `error.message`.
* Nie ponawiaj błędów `4xx` bez zmian: najpierw popraw żądanie. Wyjątkami są `409` dla żądania, które wciąż trwa, oraz `429`.
* Przy `429` odczekaj liczbę sekund podaną w nagłówku `Retry-After`. Zobacz [Limity żądań](https://docs.getqr.com/pl/api/rate-limits.md#po-przekroczeniu-limitu).
* Ponawiaj błędy `5xx` z wykładniczym wydłużaniem odstępów.

## Typowe problemy

> [accordion] Każde żądanie zwraca 404 "This endpoint is not available."
>
> API jest w wersji beta i nie zostało jeszcze włączone dla Twojego obszaru roboczego.

> [accordion] 404 "This endpoint does not exist."
>
> Ścieżka jest nieprawidłowa. Porównaj ją ze stronami endpointów i sprawdź, czy zaczyna się od `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> Subskrypcja właściciela obszaru roboczego wygasła. Klucz API zacznie znowu działać, gdy tylko właściciel odnowi subskrypcję.

> [accordion] 403 "API access is not available for this role."
>
> Masz w obszarze roboczym rolę przeglądającego. Z API mogą korzystać tylko właściciel obszaru roboczego i edytorzy.

## Co dalej

> [card] [Limity żądań](https://docs.getqr.com/pl/api/rate-limits.md)

> [card] [Uwierzytelnianie](https://docs.getqr.com/pl/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.