Najważniejsze wnioski
- Komunikat o błędzie powinien powiedzieć użytkownikowi, co wymaga poprawy i jak wykonać kolejną czynność, a nie jedynie informować, że operacja się nie udała.
- W formularzu błędy należy wskazywać przy konkretnych polach, podsumować przed formularzem oraz obsłużyć fokusem i semantyką dostępną dla klawiatury oraz czytnika ekranu.
- Komunikat dla użytkownika, log techniczny i odpowiedź API pełnią różne role. Szczegóły diagnostyczne powinny trafić do logów, nie do interfejsu ani publicznej odpowiedzi HTTP.
- Automatyczne ponawianie ma sens tylko w wybranych błędach przejściowych i wymaga limitów, opóźnień oraz ochrony przed podwójnym wykonaniem operacji.
- Widget WCAGbot może wspierać komfort korzystania ze strony, ale nie naprawi źródłowo błędnej walidacji, nieprawidłowego fokusu ani niejasnych komunikatów formularza.
Dla zarządzającego
Obsługa błędów jest elementem jakości usługi i procesu sprzedaży: ogranicza porzucone formularze, zmniejsza liczbę zgłoszeń do obsługi oraz pomaga szybciej wykrywać problemy operacyjne. Priorytetem powinny być krytyczne ścieżki: rejestracja, logowanie, koszyk, dostawa, płatność i kontakt.
Dla sprzedaży
Jeżeli klient nie rozumie komunikatu po błędnym kodzie pocztowym, odrzuconej płatności lub braku wymaganego pola, może przerwać zakup. Zespół sprzedaży i obsługi klienta powinien przekazywać zespołowi produktu powtarzające się pytania użytkowników oraz identyfikatory zgłoszeń widoczne w komunikatach awaryjnych.
Obsługa błędów powinna prowadzić użytkownika od problemu do konkretnego działania naprawczego. W sklepie internetowym oznacza to przede wszystkim zrozumiałe błędy w formularzu adresu, logowania i płatności, a po stronie technicznej — spójne odpowiedzi API, bezpieczne logi oraz kontrolowane ponowienia.
To nie jest wyłącznie detal interfejsu. Jeżeli użytkownik nie wie, dlaczego formularz nie został wysłany albo gdzie poprawić dane, może porzucić zakup, wysłać zgłoszenie do obsługi lub wielokrotnie wykonać tę samą czynność. Z perspektywy dostępności cyfrowej błędny komunikat może dodatkowo całkowicie zablokować osobę korzystającą z klawiatury, powiększenia lub czytnika ekranu.
Najważniejsze wnioski:
- opisuj problem prostym językiem i wskazuj następny krok;
- łącz komunikat z konkretnym polem formularza także programowo;
- nie kasuj danych, które użytkownik wpisał poprawnie;
- oddziel komunikat dla użytkownika od danych diagnostycznych dla zespołu;
- testuj błędy tak samo uważnie jak scenariusze powodzenia.
Czym jest dobra obsługa błędów?
Dobra obsługa błędów to zaprojektowany proces wykrywania problemu, przekazania zrozumiałej informacji, umożliwienia korekty oraz zapisania danych potrzebnych do diagnozy. Dotyczy zarówno prostego komunikatu „Podaj adres e-mail”, jak i awarii integracji z operatorem płatności.
W kontekście WCAG kluczowe znaczenie mają między innymi identyfikacja błędu, sugestia jego poprawy oraz komunikaty o stanie. W3C wskazuje w kryterium 3.3.1, że wykryte błędy wejścia powinny zostać zidentyfikowane, a element zawierający błąd — wskazany, gdy jest to możliwe. Z kolei kryterium 3.3.3 dotyczy sugestii poprawy, jeśli jest znana i nie narusza bezpieczeństwa.
Komunikat o błędzie nie kończy zadania użytkownika. Powinien otwierać najkrótszą drogę do jego dokończenia.
Jak powinien wyglądać komunikat o błędzie w formularzu?
Najlepszy komunikat nie wymaga domyślania się. Zamiast „Nieprawidłowe dane” użyj informacji: „Podaj adres e-mail w formacie nazwa@domena.pl”. Zamiast „Błąd płatności” użyj: „Nie udało się potwierdzić płatności. Sprawdź dane karty lub wybierz inną metodę płatności.” Jeśli przyczyna leży po stronie systemu, nie przerzucaj odpowiedzialności na użytkownika: „Płatność jest chwilowo niedostępna. Spróbuj ponownie za chwilę albo wybierz inną metodę.”
| Element | Co wdrożyć | Czego unikać |
|---|---|---|
| Podsumowanie błędów | Umieść je przed formularzem i wypisz liczbę oraz nazwy problemów. | Ogólnego komunikatu bez wskazania pól. |
| Błąd przy polu | Dodaj tekstowy opis bezpośrednio przy polu i połącz go programowo z kontrolką. | Samej czerwonej ramki lub ikony bez opisu. |
| Fokus po wysłaniu | Przenieś fokus do podsumowania błędów albo pierwszego błędnego pola — konsekwentnie w całym serwisie. | Pozostawienia fokusu na przycisku „Wyślij”, gdy błąd jest poza aktualnym widokiem. |
| Dane użytkownika | Zachowaj wcześniej wpisane poprawne wartości. | Czyszczenia całego formularza po jednym błędzie. |
| Kolor i kontrast | Użyj tekstu, ikon i czytelnego oznaczenia, nie opieraj znaczenia tylko na kolorze. | Komunikatu rozróżnialnego wyłącznie po czerwonym kolorze. |
| Stan po poprawie | Usuń lub zaktualizuj błąd, gdy dane są poprawne. | Pozostawiania nieaktualnego ostrzeżenia. |
Widoczny fokus jest równie ważny jak sam komunikat. Warto sprawdzić, czy po wysłaniu formularza fokus nie jest zasłonięty przez stały nagłówek, baner lub okno modalne. Pomocne będą artykuły o widocznym fokusie, fokusie niezasłoniętym oraz wyglądzie fokusu.
Ścieżka obsługi błędu w formularzu
Jak połączyć błąd z polem dla czytnika ekranu?
Widoczny tekst błędu musi mieć także poprawną relację w kodzie. Pole można oznaczyć stanem błędu przez aria-invalid="true", a jego opis powiązać przez aria-describedby z identyfikatorem komunikatu. Nie należy dodawać ARIA automatycznie bez sprawdzenia, czy relacje, etykiety i aktualizacje stanu są rzeczywiście poprawne.
Komunikat pojawiający się po akcji użytkownika może wymagać mechanizmu powiadamiającego technologię asystującą. W3C opisuje to w WCAG 4.1.3 Status Messages. Dobór rozwiązania zależy od sytuacji: podsumowanie błędów po wysłaniu formularza zwykle wymaga także świadomego zarządzania fokusem, natomiast krótka informacja typu „Kod rabatowy został zastosowany” może być przekazana jako komunikat o stanie bez zmiany fokusu.
Przed wdrożeniem sprawdź podstawy semantyki. Nieprawidłowa struktura HTML i nadmiarowe role ARIA często sprawiają, że nawet dobry tekst błędu jest odczytywany w niewłaściwej kolejności. Zobacz poradniki: HTML semantyczny oraz ARIA w praktyce.
WCAGbot Accessibility Path: proces wdrożenia obsługi błędów
WCAGbot Accessibility Path porządkuje pracę nad barierami związanymi z błędami. Jest to proces, a nie deklaracja zgodności strony z WCAG.
- Wybierz ścieżki krytyczne. Spisz formularze kontaktowe, logowanie, tworzenie konta, odzyskiwanie hasła, koszyk, adres dostawy, rabaty i płatność.
- Zbierz realne błędy. Dla każdego formularza wypisz brakujące dane, zły format, konflikt danych, limit prób, timeout i awarię usługi zewnętrznej.
- Zaprojektuj trzy warstwy komunikacji. Ustal osobno tekst dla użytkownika, kontrakt API oraz zakres logu technicznego.
- Wdróż semantykę i fokus. Dodaj etykiety, opisy, powiązania błędów, widoczny fokus i obsługę klawiatury.
- Przetestuj scenariusze negatywne. Sprawdź je myszą, klawiaturą i czytnikiem ekranu, a następnie popraw źródło problemu.
- Utrzymuj i mierz. Monitoruj powtarzające się błędy, zgłoszenia do supportu oraz problemy pojawiające się po aktualizacjach.
Jak rozdzielić komunikat dla użytkownika, API i log?
Jedna treść nie powinna obsługiwać wszystkich odbiorców. Użytkownik potrzebuje jasnej instrukcji. Integracja potrzebuje przewidywalnego kodu i formatu. Zespół techniczny potrzebuje kontekstu diagnostycznego, ale ten kontekst może zawierać informacje, których nie wolno ujawniać publicznie.
Dla HTTP API warto stosować spójny kontrakt błędów. RFC 9457 opisuje format application/problem+json z polami takimi jak type, title, status, detail i instance. Pole detail ma pomagać klientowi skorygować problem, a nie pokazywać stack trace, ścieżkę serwera, nazwę tabeli bazy danych czy wersję frameworka.
Przykład bezpiecznej odpowiedzi dla błędu walidacji:
{
"type": "https://example.com/problems/invalid-email",
"title": "Nie można zapisać formularza",
"status": 422,
"detail": "Sprawdź pola oznaczone jako błędne.",
"instance": "urn:request:abc123",
"errors": [{
"field": "email",
"code": "invalid_format",
"message": "Podaj poprawny adres e-mail."
}]
}Identyfikator instance lub identyfikator żądania może być podany użytkownikowi przy błędzie technicznym. Ten sam identyfikator powinien znaleźć się w logu. Dzięki temu obsługa klienta może przekazać zgłoszenie zespołowi technicznemu bez proszenia użytkownika o zrzut konsoli albo dane wrażliwe.
Trzy warstwy informacji o błędzie
OWASP zaleca centralne zarządzanie wyjątkami oraz ochronę przed ujawnianiem danych o implementacji. Szczegóły znajdziesz w Error Handling Cheat Sheet OWASP.
Kiedy można automatycznie ponowić operację?
Nie każdy błąd oznacza „spróbuj jeszcze raz”. Dla błędów walidacji, braku uprawnień czy nieistniejącego zasobu użytkownik lub system musi najpierw zmienić dane, poświadczenia albo uprawnienia. Ponowienie bez zmiany niczego nie naprawi.
Ostrożne retry może mieć sens przy części błędów przejściowych, takich jak chwilowa niedostępność usługi lub przekroczony limit żądań. Mechanizm powinien mieć limit prób, rosnące opóźnienie, losowe rozproszenie czasu prób oraz obsługę nagłówka Retry-After. Przy operacjach zapisu trzeba dodatkowo zabezpieczyć się przed podwójnym obciążeniem karty, utworzeniem dwóch zamówień albo wysłaniem dwóch wiadomości. Pomagają w tym klucze idempotencji i jednoznaczny status operacji.
To szczególnie ważne na etapie checkoutu. Przeczytaj także poradnik o płatności online, bezpieczeństwie i dostępności, aby połączyć komunikaty o błędach z bezpiecznym przebiegiem płatności.
Mini-scenariusz: błąd w formularzu dostawy
Scenariusz ilustracyjny — nie opisuje wdrożenia u konkretnego klienta. Użytkownik sklepu przechodzi do kroku dostawy, wpisuje kod pocztowy w nieobsługiwanym formacie i wybiera „Przejdź do płatności”.
- Formularz nie przechodzi do kolejnego kroku.
- Nad formularzem pojawia się podsumowanie: „Formularz zawiera 1 błąd: kod pocztowy”.
- Fokus trafia do podsumowania, w którym link prowadzi do pola kodu pocztowego.
- Przy polu widoczny jest komunikat: „Wpisz kod w formacie 00-000”. Pole ma programowo określony stan błędu i powiązany opis.
- Imię, ulica, miasto oraz inne prawidłowo wpisane dane pozostają zachowane.
- Po wpisaniu poprawnego kodu błąd znika, a użytkownik może kontynuować bez powtarzania całego formularza.
Warto następnie wykonać ten scenariusz samą klawiaturą i w czytniku ekranu. Praktyczny proces opisuje artykuł NVDA: testowanie dostępności, a szerszą listę kontroli znajdziesz w materiale testy po wdrożeniu.
Czego nie naprawi widget dostępności?
WCAGbot może być szybkim pierwszym krokiem do dostępności: po dodaniu jednej linii kodu udostępnia między innymi funkcje kontrastu, powiększania tekstu, czytania treści, ustawienia typografii oraz narzędzia wspierające fokus i nawigację. Użytkownik może na własnej stronie otworzyć panel, zwiększyć tekst albo przetestować wybrany tryb kontrastu.
Jednocześnie widget nie zastępuje audytu i naprawy źródłowej. Nie zmieni samodzielnie niejasnego tekstu „Błąd”, nie ustali właściwej logiki walidacji, nie zapewni bezpiecznej obsługi ponowień ani nie zagwarantuje prawidłowego przenoszenia fokusu w niestandardowym formularzu. Te bariery wymagają pracy w kodzie, treści i procesie testów.
Podsumowanie dla zarządzającego i sprzedaży
Obsługa błędów zasługuje na miejsce w backlogu jakości, a nie wyłącznie w liście „drobnych poprawek”. W pierwszej kolejności warto ocenić miejsca, w których błąd zatrzymuje zakup, kontakt lub dostęp do konta. Każdy z tych punktów powinien mieć właściciela, zdefiniowane scenariusze negatywne i test po aktualizacji.
Dostępny błąd w formularzu zamówienia
Dla zespołu sprzedaży i obsługi klienta przydatne są komunikaty zawierające bezpieczny identyfikator zdarzenia oraz prostą informację, co klient może zrobić dalej. Dla zespołu technicznego przydatne są spójne typy błędów, korelacja z logami i regularne sprawdzanie, czy wdrożone poprawki działają także z klawiaturą oraz czytnikiem ekranu.
FAQ: obsługa błędów
Czy sam czerwony kolor wystarczy do oznaczenia błędu?
Nie. Kolor może wspierać przekaz, ale nie powinien być jedynym nośnikiem informacji. Dodaj widoczny opis tekstowy, odpowiednie oznaczenie pola i czytelny kontrast.
Gdzie przenieść fokus po wysłaniu formularza z błędami?
Najczęściej do podsumowania błędów umieszczonego przed formularzem albo do pierwszego błędnego pola. Wybierz jedno zachowanie zgodne z architekturą formularza i testuj je z klawiaturą oraz czytnikiem ekranu.
Czy trzeba wyświetlać podsumowanie błędów i komunikat przy polu?
W rozbudowanych formularzach warto stosować oba rozwiązania. Podsumowanie szybko informuje, że wystąpił problem i umożliwia przejście do pola, a komunikat przy polu wyjaśnia, co dokładnie poprawić.
Czy komunikat „Pole jest wymagane” jest wystarczający?
Jest lepszy niż ogólne „Błąd”, ale często można podać więcej kontekstu, na przykład „Podaj numer telefonu do kontaktu z kurierem”. Komunikat powinien odpowiadać celowi danego pola.
Czy należy kasować hasło po błędzie formularza?
To zależy od modelu bezpieczeństwa i ryzyka. Nie zapisuj haseł w sposób niebezpieczny ani nie ujawniaj ich w komunikatach. Dla pozostałych pól zasadą użyteczności jest zachowanie prawidłowo wprowadzonych danych.
Czy błędy API mogą zawierać stack trace?
Nie w publicznej odpowiedzi. Stack trace i szczegóły implementacji mogą ujawniać informacje pomocne w ataku. Umieść je w chronionych logach, a użytkownikowi lub klientowi API zwróć bezpieczny komunikat i identyfikator zdarzenia.
Kiedy odpowiedź 422 jest lepsza niż 400?
To zależy od przyjętego kontraktu API. Często 400 oznacza nieprawidłową składnię lub parametry żądania, a 422 — dane poprawne strukturalnie, lecz nieakceptowalne z powodu reguł walidacyjnych albo biznesowych. Najważniejsza jest konsekwencja oraz dokumentacja.
Czy wolno automatycznie ponawiać płatność po błędzie 500 lub timeout?
Nie bez dodatkowych zabezpieczeń. Przy operacji finansowej najpierw ustal jej faktyczny status i stosuj mechanizm idempotencji. W przeciwnym razie można przypadkowo powielić obciążenie lub zamówienie.
Jak przetestować błędy klawiaturą?
Wypełnij formularz celowo nieprawidłowymi danymi, wyślij go bez użycia myszy i sprawdź kolejność fokusu, widoczność oznaczenia, możliwość przejścia do błędnych pól oraz możliwość poprawienia i ponownego wysłania danych.
Czy WCAGbot zapewnia zgodność formularza z WCAG?
Nie. WCAGbot udostępnia funkcje wspierające dostępność użytkownikom, ale nie zastępuje audytu, testów z użytkownikami ani naprawy błędów w kodzie i treści formularza.
Od czego zacząć poprawę obsługi błędów w sklepie?
Zacznij od ścieżek o największym znaczeniu dla użytkownika i biznesu: logowania, rejestracji, odzyskiwania hasła, koszyka, danych dostawy oraz płatności. Spisz możliwe błędy i przejdź każdy scenariusz na komputerze oraz urządzeniu mobilnym.
Dodaj funkcje dostępności swojej strony i przetestuj WCAGbot. Dodaj funkcje dostępności.
