← Dokumentacja API

Kody błędów

Każdy błąd ma Content-Type: application/problem+json, pole code z listy poniżej i type wskazujące na tę stronę.

• unauthorizedHTTP 401 · Unauthorized

  Brak nagłówka Authorization, zły, unieważniony lub wygasły klucz. Nie ponawiaj.

• insufficient_scopeHTTP 403 · Insufficient scope

  Klucz nie ma scope’u wymaganego przez endpoint (`requiredScopes`). Utwórz klucz z tym scope’em.

• forbiddenHTTP 403 · Forbidden

  Operacja niedozwolona dla klucza API (np. zarządzanie kluczami).

• not_foundHTTP 404 · Not found

  Zasób nie istnieje w Twojej firmie (lub nieznany endpoint).

• method_not_allowedHTTP 405 · Method not allowed

  Zła metoda HTTP — dozwolone są w nagłówku `Allow`.

• validation_failedHTTP 400 · Validation failed

  Błędne dane — lista pól w `errors` (ścieżka pola → komunikat). Popraw i wyślij ponownie.

• invalid_jsonHTTP 400 · Invalid JSON body

  Body nie jest poprawnym JSON-em.

• api_key_in_urlHTTP 400 · API key in URL

  Klucz API pojawił się w adresie URL. Odrzucamy takie żądania — unieważnij ten klucz i wysyłaj go tylko w nagłówku.

• idempotency_key_requiredHTTP 400 · Idempotency-Key header required

  `POST /invoices` wymaga nagłówka `Idempotency-Key` (np. UUID).

• idempotency_key_mismatchHTTP 422 · Idempotency-Key reused with a different payload

  Ten `Idempotency-Key` był użyty z inną treścią żądania w ciągu 24 h. Użyj nowego klucza.

• idempotency_in_progressHTTP 409 · Request with this Idempotency-Key in progress

  Żądanie z tym `Idempotency-Key` jeszcze trwa. Ponów po chwili — dostaniesz jego wynik.

• conflictHTTP 409 · Conflict

  Konflikt, np. limit 10 aktywnych kluczy lub webhooków.

• invalid_stateHTTP 409 · Invalid state

  Operacja niedozwolona w obecnym stanie, np. edycja wystawionej faktury (użyj korekty).

• plan_requiredHTTP 402 · Plan upgrade required

  Funkcja wymaga planu Pro (API). Zmień plan w Ustawienia → Plan i płatności.

• read_onlyHTTP 402 · Account is read-only

  Konto tylko do odczytu (zaległa płatność > 7 dni). Odczyty działają, zapisy nie.

• plan_limitHTTP 429 · Plan limit reached

  Osiągnięty limit planu (np. faktur w miesiącu).

• rate_limitedHTTP 429 · Too many requests

  Za dużo żądań (60/min, 600/h na klucz). Poczekaj `Retry-After` sekund.

• payload_too_largeHTTP 413 · Payload too large

  Body większe niż 1 MB.

• unsupported_media_typeHTTP 415 · Unsupported media type

  Wysyłaj JSON z `Content-Type: application/json`.

• not_implementedHTTP 501 · Not implemented

  Endpoint jeszcze niedostępny.

• not_supported_yetHTTP 422 · Not supported yet

  Funkcja jest w kontrakcie, ale na razie wyłączona (np. faktury zaliczkowe) — szczegóły w details.

• external_unavailableHTTP 503 · Upstream service unavailable

  Usługa zewnętrzna (np. magazyn plików, rejestr GUS) chwilowo niedostępna. Ponów z backoffem.

• internalHTTP 500 · Internal error

  Nieoczekiwany błąd po naszej stronie. Ponów z backoffem; podaj `requestId` w zgłoszeniu.