W wielu interfejsach błąd wygląda tak samo: użytkownik dostaje kod, krótki techniczny skrót albo „coś poszło nie tak”. Tyle że to rzadko pomaga podjąć decyzję: co poprawić, co sprawdzić i jak szybko wrócić do zadania. Dlatego komunikaty błędów w UI muszą być pisane jak instrukcje, a nie jak logi.
Dobre podejście daje standard Problem Details (RFC 7807). Zamiast tworzyć własne, różne formaty błędów dla każdego API, dostajesz ustrukturyzowane pola: m.in. type, title, status i detail. Copy UX polega na tym, by rozdzielić: co z tych pól jest treścią dla człowieka, a co ma służyć logice mapowania. W tym artykule przełożymy to na praktyczne wzorce mikrocopy.
Skupimy się na typowych problemach: unikaniu „technicznym echem” z API, bezpiecznym tłumaczeniu kodów na instrukcje oraz planowaniu rodzin komunikatów (np. walidacja vs błąd systemowy). Na końcu dostaniesz checklistę do szybkiej weryfikacji gotowych tekstów.
Co daje RFC 7807 w copy UX — rozdzielenie danych o błędzie od języka użytkownika
Dlaczego „techniczny” błąd w UI psuje decyzje użytkownika
Techniczny komunikat psuje UX, bo miesza rolę informacji. Użytkownik nie chce zgadywać, co oznacza identyfikator, status czy typ problemu. Chce wiedzieć dwie rzeczy: co dokładnie poszło nie tak oraz co zrobić dalej.
Gdy w UI pojawia się kod albo nazwa klasy błędu, to zwykle dzieje się jedno z dwóch: albo użytkownik nie rozumie treści i tylko czeka, albo próbuje „na ślepo” zmieniać dane, co zwiększa frustrację i ryzyko błędów powtórnych. Co gorsza, zespół productowy podejmuje decyzje copy na oko, bo każdy przypadek wygląda jak osobna historia.
RFC 7807 porządkuje samą strukturę przekazywania informacji o błędzie w odpowiedziach HTTP. To ważne dla copy UX, bo zamiast pisać komunikaty „od zera” dla każdego wariantu błędu, można budować spójne wzorce: krótkie title dla klasy problemu oraz opis detail dla konkretnego wystąpienia. W efekcie UI dostaje język, a mapowanie przestaje być improwizacją.
Mapowanie pól Problem Details: type, title, status, detail — do czego używać w UI
Przykładowa struktura treści dla użytkownika (szablon myślenia)
W copy UX warto traktować pola Problem Details jak cztery różne funkcje w komunikacie. Nie wszystkie są po to, by stały się zdaniem widocznym dla użytkownika.
- type: potraktuj jako identyfikator klasy problemu i podstawę do wyboru szablonu mikrocopy (czy to walidacja, limit, konflikt danych, czy błąd innego typu).
- title: wykorzystaj jako krótki, powtarzalny opis typu problemu w UI. To kandydat do lokalizacji, bo dobrze „niesie” sens bez wchodzenia w szczegóły.
- status: potraktuj jako pomocniczą informację techniczną dla logiki mapowania. Z perspektywy użytkownika zwykle to nie jest finalny tekst, który ma brzmieć jak instrukcja.
- detail: wykorzystaj jako kontekst konkretnego przypadku. Ma tłumaczyć „co się stało w tym jednym wystąpieniu”, ale nadal ma brzmieć po ludzku.
Praktyczny szablon myślenia wygląda prosto: najpierw pokazujesz użytkownikowi krótko „co się stało” (najczęściej title), a potem dopowiadasz „w tym przypadku” (najczęściej detail). Kody i identyfikatory nie powinny być treścią samą w sobie — ich rolą jest sterowanie, który tekst wyświetlić.
Jeśli detail brzmi jak zapis dla systemu, nie bój się go „przepisać” redakcyjnie: zostawić sens, usunąć techniczne echo i dopasować składnię do języka użytkownika. W ten sposób Problem Details staje się źródłem informacji, a nie gotowcem do wklejenia.
Instrukcje i mikrocopy dla błędów: identyfikacja + sugestia korekty (bez obietnic)
Jak rozpoznać granicę między kontekstem a debugiem
Standard dla UXcopy można streścić w dwóch krokach: identyfikacja błędu i podpowiedź, co poprawić. Wymóg „identyfikacji” oznacza, że użytkownik ma dostać tekstową informację, co jest nie tak. Wymóg „sugestii” oznacza, że — jeśli to możliwe — mikrocopy ma wskazywać kierunek korekty.
Granica między kontekstem a debugiem jest zwykle słyszalna w zdaniach. Kontekst odpowiada na pytanie: „co dokładnie było problemem w tym przypadku?”. Debug brzmi jak: „dlaczego system w tej konkretnej implementacji nie przeszedł walidacji” albo jak lista szczegółów, które pomagają deweloperowi odtworzyć awarię.
- Jeśli zdanie da się przerobić na instrukcję dla użytkownika (np. „sprawdź dane w polu…”, „użyj formatu…”, „powtórz po zmianie…”) — to prawdopodobnie kontekst.
- Jeśli zdanie przypomina raport, diagnozę lub komunikat o stanie systemu — zwykle to materiał debugowy. Wtedy potrzebujesz uboższego, bardziej użytkowego opisu.
- Jeśli użytkownik, po przeczytaniu samego detail, nie wie „co teraz”, prawdopodobnie brakuje sugestii korekty. Dodaj ją redakcyjnie, ale bez obietnic.
W praktyce warto pisać instrukcję jako podpowiedź, a nie obietnicę efektu. Nawet gdy detail sugeruje przyczynę, zawsze zostaw miejsce na to, że użytkownik może nie mieć pełnego wpływu (np. gdy błąd wynika z danych zewnętrznych). Twoim celem jest kierować do działania, a nie obiecywać rezultat.
Walidacja vs błąd systemowy: jak planować rodziny komunikatów i tłumaczenia
Proces redakcyjny: od szablonu do wersji językowej
Żeby tłumaczenia i spójność nie rozpadły się w produkcji, planuj komunikaty jako rodziny. Najprostszy podział to walidacja vs błąd systemowy, bo UXcopy w obu sytuacach pełni inną rolę: w walidacji użytkownik poprawia dane, a w błędzie systemowym użytkownik zwykle potrzebuje informacji i bezpiecznej ścieżki dalszych kroków.
Proces redakcyjny zacznij od struktury, a dopiero potem przechodź do wersji językowych. Najpierw ustaw, które fragmenty są stałe, a które są kontekstowe. Tu znowu pomaga RFC 7807: title może pełnić rolę „komunikatu klasy” i dobrze się lokalizuje, natomiast detail może zawierać „komunikat kontekstowy”, który dopasowujesz tak, by był naturalny po wyświetleniu.
- Najpierw: zbuduj mapę rodzin (np. walidacja wejścia, błąd systemowy). Dla każdej rodziny przygotuj szablony mikrocopy o podobnym stylu.
- Następnie: dla każdej klasy problemu wybierz, jak ma brzmieć title (krótko, powtarzalnie, bez technicznego słownictwa).
- Na końcu: przepisz detail tak, by tłumaczył konkretny przypadek, ale nie dodawał detali implementacyjnych.
Takie podejście pozwala też kontrolować, czy komunikaty nie zaczynają być jednym wielkim „uniwersalnym tekstem”. W praktyce walidacja i błąd systemowy powinny mieć różne kierunki: w jednym użytkownik korekty dokonuje od razu, w drugim potrzebuje uspokajającej informacji i jasnej ścieżki co dalej.
Checklist: czy komunikat nie jest „technicznym echem” z API?
Szybki test „dla nie-dewelopera”
Jeśli w komunikacie użytkownik widzi tylko kod albo powtarza się identyfikator techniczny, to zwykle nie jest to gotowy tekst UX. Żeby to złapać, użyj prostego testu: przeczytaj komunikat tak, jakbyś nie znał systemu.
- Użytkownik rozumie, co jest nie tak (tekstowo). Komunikat nie wymaga odszyfrowywania.
- W komunikacie jest kierunek korekty lub wskazówka, co zrobić dalej, jeśli jest to możliwe.
- Tekst nie sprowadza się do powtórzenia technicznego kodu jako jedynego zdania.
- Treść nie brzmi jak opis dla dewelopera (brak „debugowego” charakteru w samym UI).
- Jeśli coś brzmi strasznie albo „zbyt technicznie”, to raczej nie jest to instrukcja dla człowieka.
Szybki dodatkowy test brzmi jeszcze prościej: wyobraź sobie, że usuwasz wszystkie kody i zostawiasz tylko zdania o tym, co się stało i co teraz. Jeśli bez kodów nie wiesz, co robić, dopisz sugestię korekty albo przeredaguj detail tak, by stał się kontekstem użytkowym. Dzięki temu łatwiej uniknąć sytuacji, w której komunikat użytkownika powtarza wyłącznie techniczny kod.
Bezpieczeństwo komunikatów błędów: czego unikać przy mapowaniu do UI
Zasada minimalnej użyteczności
RFC 7807 podkreśla kwestię bezpieczeństwa: problem details nie powinny być narzędziem do ujawniania szczegółów implementacji ani materiałem do debugowania przez interfejs HTTP. To oznacza jedno dla UXcopy: mapuj tylko tyle informacji, ile jest potrzebne, by użytkownik zrozumiał błąd i dostał kierunek działania.
- Nie eksponuj szczegółów, które mogłyby ułatwiać odtwarzanie problemu „od strony systemu”. Jeśli detail brzmi jak raport diagnostyczny, przeredaguj go na bardziej ogólny opis.
- Nie używaj surowych identyfikatorów i technicznych fragmentów jako jedynego komunikatu użytkownika. Błąd musi być zrozumiały, nie tylko „weryfikowalny”.
- Minimalizuj ryzyko ujawnienia informacji wrażliwych: jeśli tekst może zdradzać zbyt dużo, przenieś ciężar na instrukcję korekty i ogólny opis tego, co poszło nie tak.
„Minimalna użyteczność” nie oznacza, że komunikaty mają być krótkie za wszelką cenę. Oznacza, że powinny zawierać tylko elementy, które spełniają rolę UX: identyfikują błąd i (gdy możliwe) podpowiadają korektę. To równocześnie wspiera dostępność i ogranicza chaos w warstwie informacji.
Podsumowując: Problem Details (RFC 7807) daje ustrukturyzowane pola, ale jakość zaczyna się w UXcopy. Title i detail są najlepszymi kandydatami na treść dla użytkownika, bo opisują klasę błędu i konkretne wystąpienie. Type i status mają pracować głównie jako sterowanie mapowaniem, a nie jako „tekst do pokazania”. Komunikat ma identyfikować błąd i, jeśli to możliwe, zawierać sugestię korekty, bez straszenia technikaliami i bez debugowania systemu. Wykorzystaj checklistę i uporządkuj rodziny komunikatów pod walidację i błędy systemowe, a mapowanie przestanie być problemem, a stanie się przewidywalnym procesem.
Skontaktuj się z Aleteksty.pl, aby omówić artykuły, teksty na stronę, opisy produktów lub regularną obsługę treści.
