Błędy i jak je naprawić

Wszystkie błędy poza OAuth mają kształt Allegro — {"errors":[{"code","message","details","path","userMessage"}]}. Opieraj logikę na code; userMessage możesz pokazać sprzedawcy. Walidacja oferty zwraca wszystkie problemy naraz. Błędy OAuth (401 tokenu, /auth/oauth/*) mają format {"error","error_description"}.

{
  "errors": [
    {
      "code": "ConstraintViolationException.MissingRequiredParameters",
      "message": "Brak wymaganego parametru 225693 (EAN (GTIN)).",
      "details": "225693",
      "path": "productSet[0].product.parameters",
      "userMessage": "Brak wymaganego parametru 225693 (EAN (GTIN))."
    }
  ]
}

Co robić przy kodach HTTP

HTTP	Postępowanie
400	Zły parametr zapytania — popraw według `message` i `path`; nie ponawiaj bez zmian.
401	Brak, zły, wygasły albo odwołany token lub klucz. Odśwież token raz i ponów; klucz — sprawdź w panelu, czy jest aktywny i czy Twój adres IP jest na liście.
403	Brak uprawnień albo blokada (zakres, konto, kwarantanna, obsługa zamówień) — ponawianie nic nie da; zobacz kod.
404	Nie ma takiego zasobu (albo należy do innego sprzedawcy) — sprawdź identyfikator.
405	Metoda nieobsługiwana — nagłówek `Allow` podaje dozwolone.
406	Zły nagłówek `Accept` — użyj `application/vnd.allegro.public.v1+json`.
409	Konflikt ze stanem zasobu — pobierz zasób ponownie (przy zmianie statusu realizacji: `INVALID_STATUS_TRANSITION` = zamówienie jest już na tym etapie albo dalej, ale `CANCELLED` po `SENT` to nie sukces; `REVISION_MISMATCH` = pobierz zamówienie ponownie).
410	Zasób usunięty (np. dokument raportu po 7 dniach) — utwórz go ponownie.
413	Treść za duża — podziel dane.
415	Zły `Content-Type` treści.
422	Niepoprawne dane — popraw wszystkie pozycje z `errors[]` naraz.
429	Limit — odczekaj `Retry-After` i ponów.
500	Błąd serwera — ponów z wykładniczym odstępem (1 s, 2 s, 4 s…); przy POST użyj `Idempotency-Key`. Zgłaszając, podaj `X-Request-Id`.
503	Funkcja chwilowo niedostępna — ponów później albo użyj zamiennika z `message`.

Wszystkie kody

Kod	HTTP	Znaczenie	Co zrobić
`invalid_token`	401	Brak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).	Odśwież token raz i ponów; przy kluczu sprawdź, czy nie został odwołany lub nie wygasł.
`AccessDenied`	403	Brak zakresu albo zasób innego sprzedawcy.	Połącz aplikację ponownie z potrzebnym zakresem (albo utwórz klucz z tym uprawnieniem).
`ACCOUNT_INACTIVE`	403	Konto sprzedawcy jest nieaktywne.	Sprzedawca musi wyjaśnić sprawę z allee.pl; GET /me/token działa nadal.
`USER_TOKEN_REQUIRED`	403	Token aplikacji (client_credentials) na trasie z danymi sprzedawcy.	Użyj tokenu sprzedawcy (authorization_code) albo klucza osobistego.
`KEY_SUSPENDED`	403	Klucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).	Sprzedawca wznawia go w panelu: Klucze API.
`KEY_QUARANTINED`	403	Kwarantanna: działa tylko odczyt (wykryto nietypowe użycie).	Sprzedawca zdejmuje kwarantannę w panelu (Klucze API → Bezpieczeństwo); sprawdź, skąd próby odczytu cudzych danych.
`ORDERS_OWNED_BY_OTHER_INTEGRATION`	403	Zamówienia sprzedawcy obsługuje inna integracja (details.owner).	Sprzedawca wskazuje Twoją aplikację w panelu: Integracje → obsługa zamówień.
`SANDBOX_ONLY`	403	Symulator sandboxu wywołany kluczem produkcyjnym.	Użyj klucza testowego allee_sk_test_…
`SANDBOX_UNSUPPORTED`	403	Operacja niedostępna w sandboxie (pliki trafiałyby do magazynu produkcyjnego).	W sandboxie podawaj zdjęcia jako URL, a wsady w treści żądania.
`NOT_FOUND`	404	Nie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).	Sprawdź identyfikator.
`METHOD_NOT_ALLOWED`	405	Metoda nieobsługiwana dla tego zasobu (nagłówek Allow podaje dozwolone).	Użyj metody z nagłówka Allow.
`NOT_ACCEPTABLE`	406	Nagłówek Accept spoza obsługiwanych typów.	Accept: application/vnd.allegro.public.v1+json (albo application/json).
`PAYLOAD_TOO_LARGE`	413	Treść żądania za duża (JSON 5 MB, faktura PDF 3 MB).	Podziel dane albo użyj wsadu z dokumentem.
`UNSUPPORTED_MEDIA_TYPE`	415	Zły Content-Type treści.	Content-Type: application/vnd.allegro.public.v1+json (faktury: application/pdf).
`JsonMappingException`	422	Treść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty).	Popraw strukturę według schematu operacji.
`UnknownJSONProperty`	422	Pole nieznane w tym miejscu (path wskazuje które).	Usuń pole albo przenieś je we właściwe miejsce.
`VALIDATION_ERROR`	400/422	Zła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.	Popraw wartość według opisu w message.
`TOO_MANY_REQUESTS`	429	Przekroczony limit (minutowy, grupy operacji albo IP).	Odczekaj Retry-After (details.retryAfterMs) i ponów; rozłóż ruch w czasie.
`TOO_MANY_CONCURRENT`	429	Za dużo ciężkich operacji naraz (wsady, raporty, duże polecenia).	Poczekaj na koniec trwających (powiadomienia FEED_/REPORT_PROCESSING_FINISHED).
`IDEMPOTENCY_KEY_INVALID`	400	Idempotency-Key: 1–100 znaków ASCII bez spacji.	Użyj np. UUID.
`IDEMPOTENCY_KEY_IN_USE`	409	Żądanie z tym kluczem jeszcze trwa.	Ponów po Retry-After — dostaniesz zapisany wynik.
`IDEMPOTENCY_KEY_REUSED`	422	Ten Idempotency-Key użyto z inną treścią albo ścieżką (24 h).	Każda nowa operacja = nowy klucz.
`INTERNAL_ERROR`	500	Błąd serwera allee.	Ponów z wykładniczym odstępem; zgłoś z X-Request-Id.
`SELLER_TYPE_CHANGE_NOT_ALLOWED`	409	Konta firmowego nie można samodzielnie zmienić na prywatne (NIP jest na fakturach i w zamówieniach).	Zmianę zgłasza sprzedawca do pomocy allee.
`MISSING_REQUIRED`	422	Brak pola wymaganego w tej sytuacji (np. companyName i taxId przy zmianie konta prywatnego na firmowe).	Dodaj pola wskazane w path i wyślij ponownie.
`DECLARATION_VERSION_OUTDATED`	409	Treść oświadczenia zmieniła się — wersja z żądania nie jest aktualna.	Pobierz GET /allee/declarations, pokaż sprzedawcy aktualną treść i wyślij details.currentVersion.
`SELLER_COMPLIANCE_INCOMPLETE`	403	Publikacja wstrzymana: profil sprzedawcy ma braki wymagane prawem (od 24.11.2026).	Sprawdź GET /allee/sellers/compliance (missing[] z severity ERROR) i uzupełnij.
`OFFER_COMPLIANCE_BLOCKED`	422	Oferta nie spełnia wymagań prawnych kategorii z blokadą (np. brak producenta GPSR, klasy energetycznej).	Szczegóły w details[] (code, path, rule) albo GET /sale/offers/{id}/compliance.
`PRODUCT_RECALLED`	422	Produkt o tym EAN jest objęty wycofaniem z rynku — nie można go wystawić.	Sprawdź komunikat wycofania (details.recall); oferta z tym produktem nie zostanie opublikowana.
`CONFLICT`	409	Operacja niemożliwa w obecnym stanie (np. zgłoszenie już rozpatrzone, odwołanie już złożone).	Sprawdź stan zasobu (GET) i wybierz właściwą operację.
`NOT_DEPLOYED`	503	Funkcja jeszcze nie uruchomiona (np. sandbox, wsady).	Użyj zamiennika z message albo spróbuj później.
`SERVICE_UNAVAILABLE`	503	Moduł chwilowo niedostępny.	Spróbuj później.
`STORAGE_UNAVAILABLE`	503	Magazyn plików chwilowo niedostępny.	Ponów za chwilę albo podaj dane inaczej (URL zdjęcia, wsad inline).
`QUEUE_UNAVAILABLE`	503	Kolejka wsadów chwilowo nie działa.	Wyślij do 500 komunikatów inline albo spróbuj później.
`CATEGORY_NOT_FOUND`	404/422	Nie ma takiej kategorii.	Weź id z GET /sale/categories albo /allee/categories.
`CATEGORY_NOT_LEAF`	422	Kategoria nie jest liściem.	Wybierz kategorię z leaf: true.
`ParameterCategoryException`	422	Parametr nie należy do kategorii.	Weź parametry z GET …/parameters tej kategorii.
`DictionaryParameterValueNotFound`	422	Wartość spoza słownika kategorii (albo Stan nieobsługiwany przez allee).	Użyj wartości ze słownika; Stan: Nowy, Używany, Odnowiony przez sprzedawcę, Uszkodzony.
`ConstraintViolationException.MissingRequiredParameters`	422	Brak wymaganego parametru lub pola (details = id parametru).	Uzupełnij według GET …/parameters.
`ConstraintViolationException.TooManyValues`	422	Kilka wartości przy multipleChoices: false.	Podaj jedną wartość.
`ConstraintViolationException.RangeValueNotSupported`	422	rangeValue nieobsługiwane.	Podaj pojedynczą wartość.
`CATALOG_PRODUCT_NOT_SUPPORTED`	422	Sama karta produktu Allegro bez danych.	Wyślij pełne dane produktu.
`IMAGE_DOWNLOAD_FAILED`	422	Adres zdjęcia niedozwolony albo nie da się go pobrać (path = które zdjęcie).	Publiczny https, port 443/80, plik JPEG/PNG/WEBP/GIF.
`IMAGE_TOO_SMALL`	—	Zdjęcie za małe (dłuższy bok < 300 px albo krótszy < 150 px) — w validation.errors.	Wyślij większe zdjęcie.
`RESPONSIBLE_PRODUCER_NOT_SPECIFIED`	422	Publikacja bez producenta GPSR.	Dodaj productSet[0].responsibleProducer albo wystaw szkic.
`SAFETY_INFO_NOT_DEFINED`	422	Publikacja bez informacji o bezpieczeństwie (GPSR).	Dodaj productSet[0].safetyInformation.
`OfferDuplicate`	409	Oferta z tym external.id (SKU) już istnieje — details = jej id.	Traktuj jako „już istnieje” i pracuj na details.
`OFFER_NOT_DRAFT`	409	Usuwać można tylko szkic nigdy nieopublikowany.	Zakończ ofertę poleceniem END.
`VARIANT_SET_NAME_INVALID`	422	Nazwa zestawu pusta albo dłuższa niż 50 znaków.	Podaj name 1–50 znaków.
`VARIANT_SET_PARAMETERS_INVALID`	422	Parametry wyboru: 1 lub 2 różne.	Np. [{"id": "54"}] (Rozmiar) albo [{"id": "color/pattern"}, {"id": "54"}].
`VARIANT_SET_TOO_FEW_OFFERS`	422	Zestaw ma mniej niż 2 oferty.	Podaj co najmniej 2 oferty.
`VARIANT_SET_TOO_MANY_OFFERS`	422	Zestaw ma więcej niż 500 ofert.	Podziel na kilka zestawów.
`VARIANT_SET_DUPLICATED_OFFER`	422	Ta sama oferta podana dwa razy.	Usuń powtórzenie.
`VARIANT_SET_PARAMETER_NOT_IN_CATEGORY`	422	Parametru nie ma w kategorii ofert (albo nie istnieje).	Weź parametr z GET /sale/categories/{id}/parameters kategorii ofert.
`VARIANT_SET_OFFER_NOT_FOUND`	422	Oferty nie ma na koncie sprzedawcy (cudza oferta = ta sama odpowiedź).	Sprawdź id oferty.
`VARIANT_SET_OFFER_NOT_BUY_NOW`	422	Licytacji nie łączymy w warianty.	Łącz tylko oferty Kup Teraz.
`VARIANT_SET_DIFFERENT_CATEGORIES`	422	Oferty z różnych kategorii.	Wszystkie oferty zestawu muszą być w tej samej kategorii-liściu.
`VARIANT_SET_OFFER_IN_OTHER_SET`	422	Oferta jest już w innym zestawie.	Usuń ją z tamtego zestawu (PUT bez niej albo DELETE).
`VARIANT_SET_OFFER_MISSING_PARAMETER`	422	Oferta nie ma wartości parametru wyboru.	Uzupełnij parametr w ofercie (PATCH /sale/product-offers/{id}).
`VARIANT_SET_OFFER_AMBIGUOUS_PARAMETER`	422	Oferta ma kilka wartości parametru wyboru.	Wariant to jedna wartość (np. jeden rozmiar) — rozdziel ofertę.
`VARIANT_SET_COLOR_PATTERN_REQUIRED`	422	Brak colorPattern przy ofercie (parametr color/pattern).	Podaj offers[i].colorPattern.
`VARIANT_SET_COLOR_PATTERN_TOO_LONG`	422	colorPattern dłuższy niż 64 znaki.	Skróć opis koloru/wzoru.
`VARIANT_SET_DUPLICATED_VARIANT`	422	Dwie oferty mają tę samą kombinację wartości (details.sameAs).	Każdy wariant musi się czymś różnić.
`VARIANT_SET_CONFLICT`	409	Równoległa zmiana zestawów (ta sama oferta dodawana naraz do dwóch zestawów).	Ponów żądanie.
`OFFER_ENDED_BY_ADMIN`	403	Ofertę zakończyła moderacja allee — nie można jej zmienić ani wznowić.	Skontaktuj się z allee.pl.
`INVALID_QUANTITY`	422	Liczba sztuk poza zakresem.	0–99 999 (przy wystawieniu co najmniej 1).
`EMPTY_STOCK`	422	Oferta bez sztuk nie może być aktywna.	Ustaw stock.available > 0.
`EMPTY_TYPE`	422	Cennik bez type.	type: PHYSICAL.
`DELIVERY_METHOD_NOT_FOUND`	422	Metoda dostawy spoza słownika allee (path = pozycja).	Weź id z GET /sale/delivery-methods albo podaj deliveryMethod.name.
`NAME_HAS_TO_BE_UNIQUE`	422	Nazwa zajęta (details = id istniejącego wpisu).	Użyj istniejącego wpisu albo innej nazwy.
`PRODUCER_NAME_HAS_TO_BE_UNIQUE`	422	Wpis GPSR o tej nazwie już jest (details = jego id).	Użyj details.
`LIMIT_EXCEEDED`	422	Limit wpisów osiągnięty (np. 50 warunków danego rodzaju).	Usuń nieużywane.
`IN_USE`	409	Wpis jest wskazany w ofercie.	Najpierw odepnij go od ofert.
`COMMAND_ID_CONFLICT`	409	Ten commandId użyto w poleceniu innego rodzaju albo u innego sprzedawcy.	Nowe polecenie = nowy UUID.
`INVALID_STATUS_TRANSITION`	409	Przejście statusu niedozwolone (details.current = bieżący).	Statusy idą tylko do przodu. Gdy chciałeś ustawić etap, na którym zamówienie już jest albo który minęło (np. PROCESSING po SENT), cel jest osiągnięty. Przy CANCELLED po SENT to NIE jest sukces — zamówienia nie da się już anulować.
`FEED_NOT_CANCELLABLE`	409	Wsad nie jest już w kolejce.	Sprawdź jego wynik.
`FEED_NOT_FINISHED`	409	Wsad jeszcze trwa.	Poczekaj na DONE (albo FEED_PROCESSING_FINISHED).
`FEED_DOCUMENT_NOT_FOUND`	422	Nie ma takiego dokumentu wsadu.	Utwórz go przez POST /allee/feeds/documents.
`INVALID_FEED_DOCUMENT`	422	Dokument wsadu ma zły kształt.	{"header":{…},"messages":[…]} — do 10 000 komunikatów.
`REPORT_NOT_CANCELLABLE`	409	Raport nie jest już w kolejce.	—
`REPORT_NOT_READY`	409	Raport jeszcze nie gotowy.	Poczekaj na DONE.
`DOCUMENT_EXPIRED`	410	Dokument raportu usunięty po 7 dniach.	Zamów raport ponownie.
`LINK_EXPIRED_OR_INVALID`	403	Podpisany link wygasł (5 min) albo jest zmieniony.	Pobierz nowy adres.
`INVALID_STATUS`	422	Status spoza listy.	Zobacz FulfillmentStatus.
`REVISION_MISMATCH`	409	Zamówienie zmieniło się od pobrania.	Pobierz zamówienie ponownie.
`SHIPMENT_REQUIRED`	422	SENT bez przesyłki.	Najpierw POST …/shipments.
`FORBIDDEN_SOURCE`	403	Ten status ustawia tylko allee (SUSPENDED, RETURNED).	—
`ORDER_NOT_READY`	409	Zamówienie jeszcze nie gotowe do realizacji.	Poczekaj na READY_FOR_PROCESSING.
`ORDER_CLOSED`	409	Zamówienie anulowane albo zakończone.	—
`CARRIER_NOT_FOUND`	404/422	Nieznany przewoźnik.	Kody z GET /order/carriers.
`CARRIER_NAME_REQUIRED`	422	ALLEGRO/OTHER bez carrierName.	Podaj carrierName.
`INVALID_WAYBILL`	422	Zły numer przesyłki.	Litery, cyfry, . _ - /; 1–64 znaki.
`LINE_ITEM_NOT_FOUND`	422	Pozycja spoza zamówienia.	Weź lineItems[].id z zamówienia.
`TOO_MANY_INVOICES`	422	Najwyżej 10 faktur na zamówienie.	—
`INVOICE_FILE_ALREADY_UPLOADED`	409	Plik tej faktury już wgrany.	Dodaj nową fakturę (np. korektę).
`INVALID_URL`	422	Zły adres faktury-linku.	Adres https.
`BUSY`	429	Ta sama operacja trwa równolegle.	Ponów po Retry-After.
`ATTACHMENTS_NOT_SUPPORTED`	422	allee nie przyjmuje załączników w wiadomościach.	Wyślij sam tekst.
`EXTERNAL_LINK`	422	Treść zawiera link spoza allee.pl.	Usuń adres.
`TEXT_EMPTY`	422	Pusta treść.	—
`TEXT_TOO_LONG`	422	Treść za długa.	Skróć.
`TEXT_INVALID`	422	Treść niedozwolona przez filtr.	Przeredaguj.
`PROFANITY`	422	Wulgaryzmy.	Przeredaguj.
`CARD_DATA`	422	Treść wygląda na dane karty płatniczej.	Nie przesyłaj danych kart.
`SENSITIVE_REQUEST`	422	Prośba o dane wrażliwe (hasła, dane logowania).	Przeredaguj.
`MESSAGE_LIMIT`	429	20 wiadomości na godzinę (wspólnie z panelem).	Odczekaj Retry-After.
`THREAD_LIMIT`	429	5 nowych rozmów na dobę.	Odczekaj.
`ORDER_REQUIRED`	422	Nową rozmowę sprzedawca zaczyna tylko w sprawie zamówienia.	Podaj order.id.
`RECIPIENT_MISMATCH`	422	recipient.login nie jest kupującym zamówienia.	—
`CHANNEL_MESSAGING`	422	Zamówienie z innego kanału sprzedaży.	Napisz w panelu tego kanału.
`NO_THREAD`	409	Sprawa nie ma rozmowy.	—
`ISSUE_ALREADY_CLOSED`	409	Sprawa już zamknięta.	—
`DEADLINE_PASSED`	409	Po terminie ustawowym reklamację można tylko uznać.	—
`INVALID_STATUS_FOR_TYPE`	422	Status nie pasuje do rodzaju sprawy.	Reklamacja: ACCEPTED/REJECTED; dyskusja: RESOLVED.
`CUSTOMER_RETURN_ALREADY_REJECTED`	409	Zwrot już odrzucony.	—
`CUSTOMER_RETURN_ALREADY_FINISHED`	409	Zwrot już zakończony.	—
`ORDER_NOT_SENT`	422	Sandbox: zwrot zamówienia, które nie było wysłane.	Najpierw przesyłka i SENT.
`DESTINATION_URL_INVALID`	422	Adres destynacji niedozwolony (https, port 443, publiczny IP).	—
`DESTINATION_VERIFICATION_FAILED`	422	Serwer nie odesłał challenge w 5 s.	Odpowiedz 2xx z {"challenge": "…"}.
`DESTINATION_REDIRECT`	422	Adres przekierowuje.	Podaj adres docelowy.
`DESTINATION_LIMIT`	409	Limit destynacji osiągnięty.	Usuń nieużywaną.
`DESTINATION_DISABLED`	409	Destynacja wyłączona.	POST …/enable.
`DESTINATION_NOT_FOUND`	422	Nie ma takiej destynacji tej aplikacji.	—
`SUBSCRIPTION_EXISTS`	409	Subskrypcja tego typu już jest.	Usuń ją albo użyj istniejącej.
`INVALID_SIGNATURE`	401	Zły podpis zgłoszenia GitHuba.	—
`invalid_client`	401	/token: zły client_id lub sekret, aplikacja nieaktywna.	Sprawdź dane aplikacji.
`invalid_grant`	400	Kod lub refresh token zły, zużyty, wygasły albo zgoda cofnięta.	Odświeżaj pojedynczo; przy cofniętej zgodzie połącz sprzedawcę ponownie.
`invalid_request`	400	Brak wymaganego pola żądania OAuth.	—
`unsupported_grant_type`	400	Nieobsługiwany grant_type.	authorization_code, refresh_token, client_credentials.
`slow_down`	429	Zbyt wiele nieudanych uwierzytelnień klienta.	Odczekaj Retry-After.