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/bad-request`

HTTP 400 Bad Request

Treść (body) nie jest prawidłowym formatem JSON, mimo że ustawiono nagłówek Content-Type: application/json (np. przecinek na końcu, obcięta lub pusta treść).

`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/unauthorized`

HTTP 401 Unauthorized

Wejściowy webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) został wywołany bez prawidłowej sygnatury lub klucza zabezpieczającego. Brakujący lub nieprawidłowy klucz API zwraca zamiast tego błąd errors/authentication.

`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/document-immutable`

HTTP 403 Forbidden

Dokument DPP przesłany z parametrem is_immutable nie może zostać usunięty.

`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/subscription-exists`

HTTP 409 Conflict

Wywołano POST /v1/billing/checkout, mimo że organizacja posiada już aktywną subskrypcję. Zmień plan w portalu rozliczeniowym.

`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 422 Unprocessable Entity

Twój bieżący plan nie pozwala na tę akcję (np. wyczerpany limit DPP lub dynamicznych kodów, zbyt duża partia, za dużo obszarów roboczych lub członków zespołu). Wymagane przejście na wyższy plan.

`errors/invalid-file-type`

HTTP 400 Bad Request

Przesłany plik ma typ, którego punkt końcowy nie akceptuje, lub jego zawartość nie pasuje do zadeklarowanego nagłówka Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Przesłany plik przekracza limit rozmiaru dla planu lub punktu końcowego.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Przesłanie pliku spowodowałoby przekroczenie całkowitego limitu pamięci obszaru roboczego lub DPP.

`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/unprocessable-entity`

HTTP 422 Unprocessable Entity

Akcja administratora jest niedozwolona (np. podszywanie się pod innego superadmina). Tylko punkty końcowe superadmina zwracają ten typ błędu.

`errors/request-error`

HTTP 4xx Client Error

Ogólny typ błędu (fallback) dla błędów klienta bez bardziej szczegółowego typu; status znajduje się w odpowiedzi. API nie posiada obecnie żadnej znanej ścieżki, która go zwraca.

`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].