Przejdź do treści
StayPark Suite · Pomoc
StayPark Suite · Pomoc
Zamknij menu
Szukaj w pomocy Ctrl K
Wprowadzenie Przewodniki Panel - obsługa Portal i aplikacje Wdrożenie i konfiguracja Integracje i API Nowości
Pomoc
Integracje i API
Kody błędów API

Kody błędów API

Zbiorcza lista kodów error.code trzech interfejsów API z kodem HTTP, znaczeniem i operacjami, które je zwracają.

Integrator

Zaktualizowano 2 listopada 2026

Na tej stronie
Podświetlone słowa z wyszukiwania: ()

Każdy błąd przychodzi w tej samej kopercie: { "success": false, "error": { "code": "...", "message": "..." } }. Program kliencki rozpoznaje błąd po error.code. Komunikat message jest po polsku i służy do pokazania użytkownikowi albo do logów. Tabele poniżej zebrano z plików OpenAPI (opisy, tabele i przykłady odpowiedzi 4xx i 5xx). Szczegóły konkretnej operacji są w dokumentacji referencyjnej (gdzie ją znaleźć).

Kody wspólne

Te kody zwraca obsługa błędów całej aplikacji, niezależnie od interfejsu:

Kod HTTP Znaczenie
VALIDATION_ERROR 422 błędy walidacji; lista pól w error.errors, komunikaty po polsku
UNAUTHENTICATED 401 brak, nieważny albo wygasły token (aplikacja pracownika i klienta)
NOT_FOUND 404 brak zasobu albo nieznana ścieżka; w aplikacji klienta także zasób cudzy albo innej marki
METHOD_NOT_ALLOWED 405 metoda HTTP niedozwolona dla tej ścieżki
HTTP_ERROR 429 i inne pozostałe błędy HTTP, przede wszystkim przekroczony limit żądań (nagłówek Retry-After)
SERVER_ERROR 500 nieobsłużony błąd serwera poza obsługą operacji; error.debug (klasa i komunikat wyjątku) tylko w trybie debugowania, nigdy ślad stosu

Każdą odpowiedź 5xx traktuj jako błąd przejściowy i ponów żądanie później.

Synchronizacja

Token, instalacja i użytkownik

Kod HTTP Znaczenie Gdzie
MISSING_AUTH_TOKEN 401 brak tokenu Bearer każda operacja
INVALID_SYNC_TOKEN 401 nieznany token każda operacja
LOCALIZATION_INACTIVE 403 token poprawny, ale lokalizacja jest wyłączona każda operacja
INSTALLATION_MISMATCH 403 token używa inny serwer lokalny (X-Sync-Installation) każda operacja
MISSING_USER_HEADER, INVALID_USER 401 brak albo nieznany X-User-Uuid operacje w imieniu pracownika
LOCALIZATION_NOT_AUTHENTICATED 401 zabezpieczenie chmury: kontekst pracownika bez uwierzytelnionej lokalizacji; przy obecnych trasach nie występuje operacje w imieniu pracownika
USER_INACTIVE, USER_NOT_IN_LOCALIZATION 403 konto nieaktywne albo nie jest pracownikiem lokalizacji operacje w imieniu pracownika
FORBIDDEN 403 brak wymaganego uprawnienia operacje w imieniu pracownika
LOCALIZATION_MISMATCH 403 localization_uuid w treści nie pasuje do tokenu POST pull, POST push

Pobieranie, wypychanie i pliki

Kod HTTP Znaczenie Gdzie
SCHEMA_VERSION_MISMATCH 400 wersja schematu kasy jest nowsza niż chmury POST pull, POST push
BATCH_LIMIT_EXCEEDED 400 ponad 500 rekordów w jednym żądaniu POST push
SYNC_ERROR 500 błąd przetwarzania; details tylko w trybie debugowania POST pull, POST push
FILE_FORBIDDEN 403 plik z magazynu prywatnego - kasa go nie dostaje GET files/{uuid}
FILE_NOT_FOUND 404 brak pliku albo jego zawartości w magazynie GET files/{uuid}

Powody w wyniku wypychania

Rekordy odrzucone w push nie dają błędu HTTP. Trafiają do skipped z powodem w errors[].reason. Opis każdego powodu: API synchronizacji.

Powód Zasoby Co zrobić
UNRESOLVED_RELATION wszystkie relacja jeszcze nieznana - kasa ponawia rekord
PENDING_DATA bill_transfers kopia rachunku w chmurze jeszcze się nie zgadza - kasa ponawia
SYNC_ERROR wszystkie wyjątek przy rekordzie - kasa ponawia
MISSING_UUID, UNKNOWN_RESOURCE, FOREIGN_RECORD wszystkie błąd kasy albo rekord innej lokalizacji - nie ponawiać bez zmiany
FOREIGN_WAREHOUSE, UNKNOWN_TYPE warehouse_movements, sale_returns magazyn innej lokalizacji / nieznany rodzaj
MISSING_TAX_RATE sale_items brak tax_rate_value
SETTLED_RECEIVABLE payments należności rozliczonej w chmurze kasa nie usunie
TOTAL_MISMATCH, RETURN_EXCEEDS_SALE sale_returns alarm operatora; ponowienie bez zmiany kwot nic nie da
INVALID_RECORD, DUPLICATE_SALE, UNKNOWN_REQUEST kuchnia, bramki, akceptacje regulaminów, marketing błąd danych kasy
CODE_COLLISION ticket_entitlements kasa nadaje biletowi nowy kod i wysyła ten sam uuid
DUPLICATE_UNIT, INVALID_ACCESS_CODE, MISSING_SALE, INVALID_STATUS bilety i ich realizacje błąd danych kasy
ERROR wszystkie inny błąd przetwarzania; w trybie debugowania zamiast ERROR przychodzi treść wyjątku

Rekordy przyjęte z ostrzeżeniem liczą się w upserted, a powód przychodzi w liście warnings. Kasa ich nie ponawia:

Powód Zasoby Znaczenie
SALE_PROCESSED_LOCKED sales, sale_items, payments sprzedaż jest już przetworzona w chmurze; zmiany kwot, stron i pozycji chmura pominęła (lista w fields, opis w message)
CANCELLATION_MISMATCH, CANCELLATION_TOTAL_MISMATCH sale_returns wypłata zwrotu z rezygnacji nie pasuje do dokumentu rezygnacji; zapisana, z alarmem operatora

Użycia promocji i kodów ponad limit oraz wejścia na bilet ponad limit chmura przyjmuje bez ostrzeżenia w odpowiedzi, ale z alarmem operatora (PROMOTION_USAGE_OVER_LIMIT, TICKET_ENTITLEMENT_OVERUSED). Te nazwy to alarmy w panelu, nie kody API.

Operacje online

Kod HTTP Znaczenie Gdzie
ORDER_NOT_FOUND 404 brak zamówienia albo zamówienie nie przyjmuje wpłat orders/{uuid}/*
PAYMENT_REFUSED 422 wpłata odrzucona, np. kwota większa niż pozostała do zapłaty; powód w message orders/{uuid}/payment-plan, payment-claims
STOCK_SHORTAGE 422 brakuje towaru do realizacji; lista w shortages POST orders/{uuid}/realizations
REALIZATION_REFUSED 422 inna odmowa otwarcia realizacji; powód w message POST orders/{uuid}/realizations
QUERY_TOO_SHORT 422 za krótkie wyszukiwanie (co najmniej 3 znaki albo pełny numer zamówienia lub telefonu) listy zamówień
RANGE_INVALID, RANGE_TOO_LONG 422 data końcowa przed początkową / zakres dłuższy niż 31 dni listy zamówień
PAYOUT_NOT_FOUND 404 brak wypłaty zwrotu w tej lokalizacji order-cancellations/.../payouts/{sale}
PAYOUT_REFUSED 422 odmowa rezerwacji wypłaty; powód w message .../payouts/{sale}/claim
COUPON_INVALID 422 kod rabatowy nieważny; powód w message coupons/check, coupons/reserve
TICKET_NOT_FOUND 404, 422 nie ma biletu o tym kodzie u operatora ticket-entitlements/*
TICKET_NOT_REDEEMABLE 422 bilet unieważniony, zablokowany, wygasły, wykorzystany, jeszcze nieważny albo z innej lokalizacji POST ticket-entitlements/redeem
TICKET_OWNER_MISMATCH 422 bilet imienny innego klienta POST ticket-entitlements/redeem
TICKET_REDEMPTION_FOREIGN 422 uuid realizacji należy do innego rachunku POST ticket-entitlements/redeem
TAKEOVER_REFUSED 422 przejęcie rachunku odrzucone, np. rachunek zamknięty albo prowadzony przez kasę POST bills/{uuid}/takeover
CHECKSUM_MISMATCH 422 suma kontrolna rachunku nie zgadza się z chmurą POST bill-transfers/{uuid}/confirm
CANCEL_REFUSED 422 przejęcie jest już zakończone POST bill-transfers/{uuid}/cancel
CUSTOMER_NOT_FOUND, BRAND_NOT_FOUND 404 nieznany klient albo marka POST customers/{uuid}/e-receipt-consent
EMAIL_REQUIRED, E_RECEIPT_REGULATION_MISSING 422 klient bez e-maila / marka bez Regulaminu e-paragonów POST customers/{uuid}/e-receipt-consent
INVOICE_NOT_FOUND 404 brak dokumentu sprzedaży tej lokalizacji GET invoices/{uuid}/pdf
PDF_NOT_AVAILABLE 404 PDF dokumentu nie jest jeszcze gotowy GET invoices/{uuid}/pdf
JOB_NOT_FOUND 404 brak zadania wydruku paragonu dla tej lokalizacji POST fiscalization-jobs/{uuid}/report
PASSWORD_NOT_ALLOWED 422 hasła nie ustawia się przez API synchronizacji POST users, PUT users/{id}
CANNOT_DELETE_SELF 422 próba usunięcia własnego konta DELETE users/{id}
GUS_NOT_CONFIGURED 503 integracja z GUS nie jest skonfigurowana GET contractors/gus

Aplikacja pracownika

Logowanie, konto i token

Kod HTTP Znaczenie Gdzie
VALIDATION_ERROR 422 złe dane logowania (pole email; ten sam błąd dla nieznanego e-maila i złego hasła) POST auth/login
TWO_FACTOR_CODE_REQUIRED 401 konto ma 2FA, a żądanie nie ma code ani recovery_code POST auth/login
INVALID_TWO_FACTOR_CODE 401 zły kod 2FA POST auth/login
TOO_MANY_ATTEMPTS 429 5 złych kodów 2FA w minutę na konto POST auth/login
HTTP_ERROR 429 ponad 5 prób logowania w minutę na parę e-mail + IP albo limit całego API (120 na minutę) POST auth/login, każda operacja
TWO_FACTOR_SETUP_REQUIRED 403 grupa uprawnień wymaga 2FA, a konto go nie skonfigurowało (konfiguracja w panelu) logowanie i każda operacja z tokenem
USER_INACTIVE 403 konto użytkownika jest nieaktywne logowanie i każda operacja z tokenem
NO_PANEL_ACCESS 403 konto nie ma dostępu do aplikacji pracownika logowanie i każda operacja z tokenem
INVALID_TOKEN_TYPE 403 token nie został wydany dla aplikacji pracownika każda operacja z tokenem
UNAUTHENTICATED 401 brak tokenu, token wygasł (30 dni bez użycia) albo unieważniony po zmianie hasła w panelu każda operacja z tokenem
FORBIDDEN 403 brak uprawnienia; nazwa w error.required_permission katalog, magazyn, spis, pełny grafik
LOCALIZATION_NOT_FOUND 404 localization_uuid nie wskazuje lokalizacji; w „Mojej pracy” - lokalizacja spoza zatrudnień konta GET barcode/{code}, GET products/{uuid}, GET products/{uuid}/price, me/*

Dokumenty magazynowe i spis z natury

Kod HTTP Znaczenie Gdzie
DOCUMENT_NOT_EDITABLE 409 dokument nie jest szkicem PUT warehouse-documents/{uuid}
DOCUMENT_NOT_DELETABLE 409 stan dokumentu nie pozwala na usunięcie DELETE warehouse-documents/{uuid}
DOCUMENT_NOT_CANCELLABLE 409 anulować można tylko szkic; zatwierdzony cofa storno POST warehouse-documents/{uuid}/cancel
DOCUMENT_VALIDATION_FAILED 409 dokumentu nie można zatwierdzić; powody w error.errors POST warehouse-documents/{uuid}/confirm
STOCK_WARNINGS 409 zatwierdzenie da ujemny stan - ponów z force: true (error.warnings) POST warehouse-documents/{uuid}/confirm
ITEM_NOT_ADDED, ITEM_NOT_UPDATED, ITEM_NOT_REMOVED 409 odmowa operacji na pozycji; powód w message warehouse-documents/{uuid}/items
DOCUMENT_NOT_CORRECTABLE 409 dokumentu nie można korygować (szkic, anulowany, wystornowany, INW, PMO i dokumenty z PMO) POST warehouse-documents/{uuid}/correction
DOCUMENT_NOT_REVERSIBLE 409 storno niemożliwe; powody w error.errors POST warehouse-documents/{uuid}/reverse
DOCUMENT_NOT_DUPLICABLE 409 kopię można zrobić tylko z PZ, WZ, MM, RW i PMO POST warehouse-documents/{uuid}/duplicate
INVENTORY_COUNT_REFUSED 409 odmowa usługi spisu: chwila odcięcia z przyszłości albo w zamkniętym okresie, spis zamknięty, nieznany kod, ilość niepodzielna inventory-counts/*
BLIND_COUNT 409 filtr różnic w spisie na ślepo w toku dla konta bez inventory_counts.confirm GET inventory-counts/{uuid}/lines?filter=differences

Moja praca

Kod HTTP Znaczenie Gdzie
SWAP_NOT_ALLOWED 409 zamiana niedozwolona (zmiana przeszła, grafik nieopublikowany, kolizja godzin, inna oczekująca prośba); powody w error.errors me/schedule-entries/{entry}/swap-targets, POST me/swap-requests, .../accept
SWAP_NOT_PENDING 409 prośba nie jest już oczekująca albo wygasła POST me/swap-requests/{uuid}/accept, reject, cancel
DECLARATION_CLOSED 409 deklaracja poza terminem wypełniania PUT me/availability-declarations/{uuid}/days/{date}
SCHEDULE_CONFLICT 409 wpis odebrałby dostępność w godzinach z opublikowanego grafiku; lista w error.errors PUT me/availability-declarations/{uuid}/days/{date}
VALIDATION_ERROR 422 złe przedziały godzin (time_slots), dzień spoza okresu (date), grupa spoza grup pracownika (preferred_group_uuid), zakres grafiku ponad 62 dni „Moja praca”

Aplikacja mobilna klienta

Marka, token i nagłówki

Kod HTTP Znaczenie
BRAND_NOT_FOUND 400 brak albo nieznana marka w X-Brand-Slug / X-Brand-UUID
BAD_REQUEST 400 ogólny błąd żądania (kod domyślny); dziś żadna operacja go nie zwraca
UNAUTHENTICATED 401 brak, nieważny albo wygasły token (90 dni)
BRAND_INACTIVE, PORTAL_DISABLED 403 marka nieaktywna / portal marki wyłączony
REAUTH_REQUIRED 401 token bez marki - zaloguj ponownie
BRAND_MISMATCH 403 token innej marki niż nagłówek
INVALID_TOKEN_TYPE 403 token nie jest tokenem aplikacji klienta
USER_INACTIVE 403 konto dezaktywowane
FEATURE_DISABLED 403 sekcja wyłączona przez markę; nazwa w error.feature
IDEMPOTENCY_KEY_REQUIRED, INVALID_IDEMPOTENCY_KEY 400 brak albo zły nagłówek Idempotency-Key
IDEMPOTENCY_KEY_REUSED 409 klucz użyty do innej operacji albo z inną treścią
IDEMPOTENCY_IN_PROGRESS 409 żądanie z tym kluczem jeszcze trwa
FORBIDDEN 403 operacja wyłączona w ustawieniach marki (rejestracja, hasła, zgody marketingowe) albo klucz kodu offline bez tokenu urządzenia; powód w message
TOO_MANY_REQUESTS 429 limit prób w operacji (error.retry_after, nagłówek Retry-After)
HTTP_ERROR 429 limit trasy (Too Many Attempts., nagłówek Retry-After)

Logowanie

Kod HTTP Znaczenie Gdzie
LOGIN_CHANNEL_DISABLED 400 kanał (e-mail albo SMS) wyłączony w marce albo identyfikator w nieznanym formacie POST auth/request-code
AUTH_ERROR 400 odmowa wysłania kodu: konto nieaktywne, nieznane konto przy wyłączonej rejestracji, kolejny kod za wcześnie, za dużo kodów; powód w message POST auth/request-code
INVALID_IDENTIFIER 400 identyfikator nie pasuje do włączonego kanału POST auth/verify-code, POST auth/login
CODE_VERIFICATION_FAILED 400 zły albo wygasły kod, za dużo błędnych prób; powód w message POST auth/verify-code
INVALID_VERIFICATION_TOKEN 400 token rejestracji wygasł, jest podrobiony albo należy do innej marki POST auth/register
REGISTRATION_FAILED 400 konto z tym adresem już istnieje, telefon ma inne konto, rejestracja wygasła; powód w message POST auth/register
PASSWORD_LOGIN_DISABLED 400 marka nie dopuszcza logowania hasłem POST auth/login
LOGIN_FAILED 400 złe hasło, konto niedostępne albo blokada po zbyt wielu próbach; powód w message POST auth/login

Konto, nagrody i e-paragony

Kod HTTP Znaczenie Gdzie
PHONE_EXISTS 409 numer telefonu należy do innego konta PATCH account
STAFF_ACCOUNT_CONTACT_LOCKED 403 e-maila i telefonu konta pracownika (z dostępem do panelu) nie zmienia się w aplikacji - zmienia je administrator w panelu PATCH account
STAFF_ACCOUNT_LOCKED 403 hasła konta pracownika nie ustawia się i nie zmienia w aplikacji, a konta nie dezaktywuje - robi się to w panelu POST account/password, PUT account/password, DELETE account
IDENTIFIER_REQUIRED 400 konto nie może zostać bez e-maila i telefonu PATCH account
PASSWORD_ALREADY_SET 409 konto ma już hasło - użyj zmiany hasła POST account/password
PASSWORD_NOT_SET 409 konto nie ma hasła - użyj ustawienia hasła PUT account/password
INVALID_PASSWORD 400 złe hasło (aktualne przy zmianie, potwierdzające przy usunięciu konta) PUT account/password, DELETE account
TOO_MANY_REQUESTS 429 5 błędnych prób zmiany hasła na konto (20 na IP) w 15 minut; error.retry_after PUT account/password
INVALID_CONFIRMATION_CODE 400 zły albo wygasły kod potwierdzający usunięcie konta DELETE account
CANNOT_REVOKE_CURRENT 409 nie można odłączyć bieżącego urządzenia - użyj wylogowania DELETE devices/{id}
REDEMPTION_REFUSED 422 odbiór nagrody odrzucony; powód w message POST rewards/{uuid}/redeem
E_RECEIPT_TERMS_NOT_ACCEPTED 422 brak akceptacji bieżącej wersji Regulaminu e-paragonów PUT account/e-receipts
EMAIL_REQUIRED 422 konto bez e-maila PUT account/e-receipts
E_RECEIPT_REGULATION_MISSING 422 marka nie ma Regulaminu e-paragonów PUT account/e-receipts

Sklep

Odmowy sklepu mają kod w error.code i pole żądania w error.field.

Kod HTTP Znaczenie
LOCALIZATION_NOT_AVAILABLE 422 sklep marki nie sprzedaje w tej lokalizacji albo produkt jest z innej lokalizacji
SHOP_OTHER_OPERATOR 422 produkt sprzedaje inny operator niż reszta koszyka - dokończ zakup albo wyczyść koszyk
SHOP_NOT_CONFIGURED, SHOP_PAYMENTS_UNAVAILABLE 422 sklep chwilowo nieczynny / płatności online niedostępne
SHOP_PRODUCT_UNAVAILABLE, SHOP_PRICE_MISSING 422 produktu nie można kupić online / brak ceny na wybrany dzień
SHOP_VARIANT_REQUIRED, SHOP_QUANTITY_LIMIT 422 brak wariantu / za dużo sztuk w jednym zamówieniu
VISIT_DATE_OUT_OF_RANGE 422 dzień wizyty poza zakresem (zakup, zmiana dnia)
SHOP_CART_EMPTY, SHOP_CART_CHANGED 422 pusty koszyk / pozycje się zmieniły - pobierz koszyk ponownie
SHOP_MAX_ORDER_VALUE 422 zamówienie przekracza najwyższą wartość zakupu online
SHOP_COUPON_INVALID 422 kod rabatowy nieważny
SHOP_COUPON_NOT_APPLICABLE 422 kod nie obniża koszyka; powody w reasons
SHOP_COUPON_REJECTED 422 kodu nie dało się zarezerwować przy złożeniu - zdjęty z koszyka
SHOP_TERMS_NOT_ACCEPTED 422 brak akceptacji bieżących wersji regulaminów (required_regulations)
E_RECEIPT_EMAIL_MISSING, E_RECEIPT_TERMS_MISSING 422 brak e-maila do e-paragonu / marka bez Regulaminu e-paragonów
INVOICE_REQUIRES_TAX_NUMBER, SHOP_BUYER_NOT_OWNED 422 faktura tylko dla firmy z NIP / nabywca spoza danych klienta
SHOP_ORDER_NOT_PAYABLE, SHOP_PAYMENT_WINDOW_PASSED, SHOP_PAYMENT_IN_PROGRESS 422 zamówienia nie można opłacić / czas na zapłatę minął / płatność trwa
SHOP_TOO_MANY_ATTEMPTS 429 za dużo startów płatności (10 na minutę)
SHOP_RETURN_REQUEST_REFUSED 422 prośby o zwrot nie można złożyć; powód w message
DAY_LIMIT_REACHED 422 zarezerwowany na limit sprzedaży na dzień wizyty - jeszcze nie występuje

Bilety

Kod HTTP Znaczenie Gdzie
TICKET_NOT_FOUND 422 nie ma biletu o tym kodzie POST ticket-entitlements/claim
ENTITLEMENT_NOT_CLAIMABLE 422 biletu nie da się przypisać do konta POST ticket-entitlements/claim
ENTITLEMENT_ALREADY_CLAIMED 422 bilet jest już na koncie POST ticket-entitlements/claim
ENTITLEMENT_NOT_CHANGEABLE 422 dnia wizyty tego biletu nie można zmienić PATCH ticket-entitlements/{uuid}/visit-date
VISIT_DATE_PRICE_DIFFERS 422 inna cena na nowy dzień - zmianę wykona obsługa PATCH ticket-entitlements/{uuid}/visit-date

Jak powstała ta lista

Tabele zebrano z plików sync.yaml (wersja 1.2), employee-app.yaml (1.4) i mobile-app.yaml (1.4) w wersji panelu z pola verified_against, a następnie porównano z kodem kontrolerów i obsługą błędów API. Po zmianie plików OpenAPI listę trzeba odświeżyć - historia wersji: Zmiany w API.

Powiązane

Brak wyników