Każdy błąd w checkout to moment, w którym użytkownik podejmuje decyzję: „czy mam jeszcze chwilę walczyć, czy wracam później?”. Jeśli zamiast zrozumiałej wskazówki widzi ogólny komunikat typu „spróbuj ponownie” albo surową treść debugującą, rośnie ryzyko porzucenia płatności. Dla zespołów e-commerce, marketingu i UX to nie jest temat „techniczny”. To temat komunikacji: co mówimy, kiedy system nie domyka kroku.
W przypadku Klarna kluczowe jest rozdzielenie dwóch warstw: danych do obsługi (m.in. error_code) oraz treści debugującej (m.in. error_message). Zgodnie z podejściem opisanym w dokumentacji, to UX ma mapować kod na zrozumiałą, zlokalizowaną informację oraz instrukcję „co dalej”. W praktyce artykuł pomoże Ci zbudować logikę i teksty, które prowadzą użytkownika po ścieżce checkout, zamiast zostawiać go z pytaniem bez odpowiedzi.
Dlaczego nie pokazywać surowego „error_message” z Klarna (i co z tego wynika dla UX)
error_code vs error_message: prosta zasada dla zespołu
W odpowiedzi błędu w integracjach płatności pojawiają się m.in. informacje o statusie HTTP oraz obiekt błędu zawierający error_code, komunikaty oraz identyfikator korelacji. Klarna opisuje, że error_code jest przeznaczony do obsługi po stronie systemu — czyli jest stabilnym, „machine-readable” identyfikatorem. Natomiast error_message ma charakter „human readable” i służy debugowaniu (jest po angielsku i nie jest przeznaczony do wyświetlania użytkownikom ani do parsowania po stronie klienta).
Ta różnica przekłada się na prostą zasadę w UX copy: wybór komunikatu UX opieraj o error_code, a nie o treść debugującą. Dopiero potem tworzysz swój tekst po polsku: zrozumiały, krótki i z instrukcją następnego kroku. Zespół, który trzyma się tej reguły, szybciej buduje spójne warianty tekstu w całym checkout, zamiast „tłumaczyć na oko” to, co przyszło z integracji.
Dlaczego „parser stringów” to zły kierunek
„Parser stringów” to praktyka, w której klient (frontend, warstwa UX, logika po stronie aplikacji) próbuje zgadywać znaczenie po surowym tekście: po fragmentach error_message albo po innych niestabilnych wątkach. Klarna wprost wskazuje, że takie podejście jest niezgodne z intencją pól debugujących: error_message nie jest narzędziem do UI, a mapowanie powinno bazować na error_code i kontekście.
W efekcie „parser stringów” zwykle kończy się kilkoma problemami: nieprzewidywalnymi wariantami komunikatów, trudniejszym utrzymaniem tekstów w kolejnych release’ach oraz brakiem kontroli nad tym, czy użytkownik dostaje instrukcję „co dalej”, czy tylko fragment komunikatu. Jeśli celem jest zatrzymanie użytkownika i prowadzenie go przez ścieżkę płatności, to właśnie przewidywalny kod oraz Twoja własna, redakcyjna wersja komunikatu powinny decydować o treści.
Mapa: kody błędów Klarna → intencja użytkownika → tekst PL („co dalej”)
Jak wygląda gotowy wpis w mapie (szablon)
Mapa to narzędzie, które łączy dane techniczne z językiem użytkownika. Dobrze przygotowany wpis ma cztery elementy: klucz mapowania, komunikat, instrukcję działania i fallback. Dzięki temu nie zostawiasz miejsca na improwizację, gdy błąd pojawia się w checkout.
- Klucz mapowania:
error_code(np. kod w formacie ALL_CAPS_SNAKE_CASED) - Intencja: krótko, „co to znaczy” dla użytkownika (np. „coś nie zostało znalezione”, „wystąpił problem wewnętrzny”, „operacja nie może się teraz udać”)
- Komunikat PL: 1–2 zdania bez debugowania, bez technicznych wstawek
- „Co dalej”: jednoznaczny następny krok w checkout (np. powrót do konkretnego etapu, ponowne przejście przez właściwy krok)
Ważne: Klarna opisuje, że internacjonalizacja powinna być po stronie klienta. To oznacza, że error_code traktujesz jak stabilny identyfikator, a treść tworzysz we własnym systemie — po polsku i w Twoim stylu.
Kiedy w mapie potrzebujesz wariantów, a kiedy wystarczy jedna treść
Nie każdy błąd wymaga wielu wersji UX. Jeśli błąd jest komunikatem o problemie, ale użytkownik wraca do tego samego punktu flow, możesz użyć jednej treści „rdzeniowej”: komunikat + instrukcja. Jeśli jednak błąd ma wpływ na to, czy użytkownik zobaczy komunikat i czy ma zostać „poproszony, aby zacząć od nowa”, przygotuj warianty.
Dokumentacja Klarna opisuje różnicę w zachowaniu błędu NOT_FOUND zależnie od operacji. W kontekście aktualizacji sesji (np. update_session) błąd bywa obsłużony w sposób, który może być „często niewidzialny” dla klienta, bo sesja może być szybko odświeżona innym mechanizmem. Natomiast w autoryzacji (np. authorize) użytkownik częściej zobaczy błąd i jest „promptowany”, by zacząć od nowa.
W praktyce oznacza to redakcyjnie: jedna mapa może mieć kilka wariantów „co dalej” dla tego samego error_code, ale zależnie od etapu checkout. Najpierw ustalasz miejsce w flow, potem piszesz instrukcję. To pozwala uniknąć sytuacji, w której tekst sugeruje działania, których użytkownik w tym momencie nie może wykonać.
Błędy typu „Something went wrong” / „500”: wzorzec UX copy, który prowadzi dalej
Gotowa struktura komunikatu (mini-formuła do skopiowania do briefu)
Dla błędów, które użytkownik może odczytać jako „coś poszło nie tak”, szczególnie ważna jest struktura. W dokumentacji Klarna pojawia się wariant opisywany jako błąd wewnętrzny (w treści odpowiedzi) z przykładem „Something went wrong internally”. Ty w UI nie tłumaczysz technicznej przyczyny. Ty prowadzisz do działania.
Wykorzystaj mini-formułę: komunikat + co dalej + co jeśli wróci problem. Tak budujesz zrozumienie bez wchodzenia w szczegóły.
- Komunikat (1–2 zdania): co się stało w prostych słowach (bez debugowania)
- „Co dalej” (jedna czynność): co użytkownik ma zrobić teraz w checkout
- Opcja awaryjna (1 zdanie): jeśli problem wróci, poproś o kontakt lub skorzystanie ze wsparcia sklepu
Jeśli chcesz ujednolicić tekst w zespole, przygotuj w briefie przykład stylu: bez technicznych nawiasów, bez surowych komunikatów z odpowiedzi, bez obietnic. Użytkownik ma wiedzieć, jaki jest następny krok, a nie poznać wewnętrzne szczegóły.
Język UX: bez debugowania, z kontekstem działania
Język UX w błędach płatności powinien być redakcyjnie konsekwentny. Najczęstszy błąd komunikacyjny to wchodzenie w szczegóły typu „nie udało się z autoryzacją” czy „błąd wewnętrzny” w wersji dosłownej, bo to brzmi jak raport dla zespołu IT. Klarna rozdziela debugowanie i komunikację — a Twoim zadaniem jest przełożyć to na działanie użytkownika.
Dlatego w tekście unikaj: wklejania error_message, cytowania fragmentów odpowiedzi, sugerowania, że użytkownik zrobi coś „poprawnie” tylko dlatego, że komunikat jest techniczny. Zamiast tego używaj słów, które odpowiadają na chwilę obecną: wróć, spróbuj ponownie w tym miejscu, przejdź przez etap jeszcze raz, sprawdź, czy wracasz tam, gdzie rozpoczęto płatność. To jest kontekst działania — i to jest „co dalej”.
„Co dalej” zależy od etapu checkout: lekcja z NOT_FOUND i różnicy between update_session i authorize
Dlaczego „prompt do startu od nowa” zmienia pisanie mikrocopy
Różnica w zachowaniu błędu NOT_FOUND zależnie od operacji to dobra lekcja dla UX copy. Jeśli użytkownik ma zostać „promptowany, by zacząć od nowa”, to treść nie może brzmieć jak proste „spróbuj ponownie”. Taki tekst sugeruje, że jest jeden, identyczny przycisk i identyczne warunki. Gdy w rzeczywistości kolejnym krokiem jest powrót do początku ścieżki, mikrocopy powinno to wspierać.
W Twojej mapie oznacza to dwa warianty instrukcji „co dalej”: jeden dla scenariuszy, gdzie użytkownik wraca w to samo miejsce (tekst może być krótszy i bardziej „lokalny”), drugi dla scenariuszy „zacznij od nowa” (tekst ma przygotować na zmianę miejsca w checkout). To jest praktyczny sposób, by nie tracić użytkownika: tekst ma prowadzić do aktualnej sytuacji, a nie do założenia o tym, co wydarzy się „gdzieś po drodze”.
Praktyczna zasada redakcyjna dla zespołu
Ustal w zespole prosty proces: najpierw miejsce błędu w flow, dopiero potem słowa. Zamiast pisać uniwersalne komunikaty, które pasują do wszystkiego, zbieraj kontekst: w którym kroku checkout błąd pojawia się użytkownikowi, i czy ma on kontynuować w tym samym miejscu, czy rozpoczynać od początku.
Ta zasada daje dwie korzyści. Po pierwsze, łatwiej ocenić, czy instrukcja „co dalej” jest wykonalna w danym widoku. Po drugie, unikniesz sytuacji, w której mapujesz ten sam error_code na jedną treść, mimo że dokumentacja opisuje różne wpływy na ścieżkę w zależności od operacji (jak wspomniany kontrast między update_session a authorize).
Checklist redakcyjny: UX copy błędu w płatnościach (żeby użytkownik rozumiał, co robić)
Szybka weryfikacja treści (copy-first)
- Czy komunikat jest po polsku, krótki i bez technicznego języka?
- Czy użytkownik po przeczytaniu wie, co ma zrobić w następnym kroku checkout?
- Czy w tekście nie pojawia się surowy
error_messagez odpowiedzi? - Czy nie obiecujesz efektu typu „na pewno zadziała” (zamiast tego prowadzisz do kolejnej czynności)?
- Czy komunikat przewiduje sytuację, że problem może wrócić, i zawiera bezpieczny fallback (np. kontakt ze wsparciem sklepu)?
Szybka weryfikacja mapowania (kod-first)
- Czy wybór wariantu UX opiera się na
error_code, a nie na treści debugującej? - Czy każdy wariant UI ma uzasadnienie w mapie (kod → intencja → komunikat → „co dalej”)?
- Czy dla błędów, które mogą mieć różny wpływ na ścieżkę, masz odpowiednie warianty „co dalej” w zależności od etapu?
- Czy fallback jest spójny stylistycznie z pozostałymi komunikatami błędów w checkout?
Jak testować te komunikaty bez obiecywania gwarancji
Test mapowania: czy treść wynika z error_code
Testy UX copy błędu warto zaplanować tak, by weryfikować logikę i czytelność, a nie „wynik biznesowy”. W praktyce sprawdzasz, czy dla danego scenariusza użytkownik widzi właściwy wariant tekstu, który pochodzi z mapy opartej o error_code.
- Porównaj wybrane scenariusze z mapą: dla każdego kodu sprawdź, czy UI wybiera komunikat zgodny z wpisem.
- Upewnij się, że w UI nigdzie nie pojawia się surowy
error_messageani fragmenty debugujące. - Zweryfikuj, że tekst jest zlokalizowany (po polsku) i nie jest kopią treści z odpowiedzi.
Test „co dalej” w flow checkout
Drugi wymiar testu dotyczy instrukcji „co dalej”. Tu chodzi o to, żeby użytkownik po błędzie rozumiał następny krok w swoim kontekście: w tym miejscu checkout, w którym faktycznie znajduje się po wystąpieniu błędu.
- Przetestuj widoki w kluczowych etapach: sprawdź, czy instrukcja pasuje do tego, czy użytkownik ma kontynuować w tym samym miejscu czy ma zostać „promptowany, by zacząć od nowa”.
- W szczególności weryfikuj przypadki, dla których dokumentacja opisuje różny wpływ błędu na ścieżkę (takie warianty wymagają różnej instrukcji, nie tylko innego zdania).
- Sprawdź fallback: jeśli problem wróci, czy komunikat prowadzi do wsparcia sklepu bez obietnic i bez technicznego debugowania?
Podsumowując: UX copy błędu Klarna payment powinno wynikać z error_code, a nie z surowego error_message, bo to drugie ma charakter debugujący i nie jest przeznaczone do UI. Następny krok to mapowanie kodu na intencję użytkownika oraz zrozumiały, zlokalizowany komunikat po polsku z jasnym „co dalej”. Pamiętaj też o kontekście etapu checkout: instrukcja musi pasować do tego, czy użytkownik zostaje poproszony o start od nowa, czy wraca do bieżącego miejsca. Skontaktuj się z Aleteksty.pl, aby omówić artykuły, teksty na stronę, opisy produktów lub regularną obsługę treści.







