Dokumentacja błędów

Wszystkie błędy API qr3.app są zgodne z RFC 7807 Problem Details i używają nagłówka Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

Dane wejściowe nie przeszły walidacji schematu. Odpowiedź zawiera tablicę errors ze szczegółami dotyczącymi poszczególnych pól.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Przyczyny: Brakujące pola wymagane, nieprawidłowe typy danych, wartości spoza dozwolonego zakresu, nieprawidłowy format URL.

`errors/authentication`

HTTP 401 Unauthorized

Klucz API jest nieobecny, nieprawidłowo sformatowany, wygasł lub został unieważniony.

Rozwiązanie: Sprawdź, czy nagłówek Authorization: Bearer qr3_sk_... jest obecny i czy klucz jest aktywny.

`errors/authorization`

HTTP 403 Forbidden

Klucz API jest prawidłowy, ale nie posiada wymaganego zakresu (scope) lub niezbędnych uprawnień.

`errors/forbidden`

HTTP 403 Forbidden

Zasób istnieje, ale należy do innego obszaru roboczego (Workspace) lub innej organizacji.

`errors/not-found`

HTTP 404 Not Found

Żądany zasób nie istnieje lub został usunięty.

`errors/conflict`

HTTP 409 Conflict

Zasób o tym samym unikalnym identyfikatorze już istnieje (np. zduplikowany slug lub kolizja klucza idempotencji Idempotency-Key).

`errors/rate-limited`

HTTP 429 Too Many Requests

Limit żądań na minutę dla klucza API został przekroczony. Odpowiedź zawiera nagłówki Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining oraz X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Limit żądań specyficzny dla danego zasobu został przekroczony (np. 200 kodów QR dziennie na Workspace).

`errors/plan-limit`

HTTP 429 Too Many Requests

Aktualny plan nie pozwala na wykonanie tej akcji (np. zbyt wiele obszarów roboczych Workspace). Wymagane przejście na wyższy plan (upgrade).

`errors/not-configured`

HTTP 503 Service Unavailable

Brak wymaganej usługi lub konfiguracji (np. Stripe nie został skonfigurowany, klucz API Web Risk nie został ustawiony).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

Adres URL został odrzucony, ponieważ został sklasyfikowany przez Google Web Risk jako niebezpieczny (malware, phishing, social engineering).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Zarezerwowane dla adresów URL, które zostały sklasyfikowane jako niebezpieczne podczas późniejszego, okresowego ponownego skanowania.

`errors/already-submitted`

HTTP 409 Conflict

Zduplikowane przesłanie — np. ocena NPS dla tego obszaru roboczego Workspace została już przesłana w tym miesiącu.

`errors/internal`

HTTP 500 Internal Server Error

Nieoczekiwany błąd serwera. Prosimy spróbować ponownie. W przypadku utrzymujących się problemów skontaktuj się z: [email protected].