„Błąd połączenia”, którego przyczyną była nazwa firmy na 66 znaków

Piętnaście prób nadania tej samej paczki skończyło się piętnastoma odmowami, a z magazynu przez ponad dobę przychodziło jedno zgłoszenie: „błąd połączenia”. Chodzi o sklep internetowy ze sprzętem sportowym, małą firmę, w której wysyłką zajmuje się magazynier, a panel do zamówień i nadawania przesyłek zbudowaliśmy my. Internet w magazynie działał, pozostałe paczki z tych dni wyszły normalnie, a ja dzień wcześniej sprawdzałem sprawę razem z magazynierem i skończyło się na niczym.

W dzienniku serwera przyczyna stała piętnaście razy, za każdym razem tym samym zdaniem: nazwa odbiorcy może mieć najwyżej 50 znaków. Zamawiająca spółka wpisała w formularzu pełną nazwę z rejestru, razem ze „spółką z ograniczoną odpowiedzialnością”, i wyszło 66. Poprawka trafiła na serwer dziesięć minut po zgłoszeniu, które wreszcie do nas dotarło na piśmie. Wcześniej przez ponad 24 godziny nikt z nas nie przeczytał zdania, które cały czas leżało w logach.

Spis treści

Piętnaście wierszy z 48 godzin

Zgłoszenie przyszło pod koniec października, w czwartek o 14:22, i nie od magazyniera, tylko od innej osoby z zespołu sklepu. Brzmiało mniej więcej tak: magazyn od ponad doby nie może nadawać paczek w panelu, wyskakuje błąd połączenia, wczoraj było to już sprawdzane i nic nie dało. To ostatnie dotyczyło mnie. W środę oglądałem problem razem z magazynierem i rozstaliśmy się bez przyczyny.

Tym razem agent AI, który opiekuje się tym panelem, zaczął od dziennika serwera z ostatnich 48 godzin. Panel przy każdej nieudanej próbie nadania zapisuje jeden wiersz: numer zamówienia, numer usługi kurierskiej i odpowiedź, jaką dostał od brokera. Takich wierszy było piętnaście. Wszystkie dotyczyły jednego zamówienia, tej samej usługi i kończyły się identycznie: „Nazwa odbiorcy: Maksymalnie 50 znaków”.

Innych błędów nadania w tym oknie nie było. Zamówienia z poprzednich trzech dni wyszły bez przeszkód, łącznie z paczką nadaną w środę przed południem, czyli już w czasie, gdy według zgłoszenia „nie dało się nadawać”. Awaria, która w rozmowach urosła do „magazyn stoi”, dotyczyła jednej przesyłki. Dla klienta, który na nią czekał, nie robi to różnicy, dla diagnozy robi ogromną: awaria łącza albo konta u brokera zatrzymałaby wszystko, a tu stała jedna paczka z jednego powodu.

Do przeczytania tych piętnastu wierszy wystarczyły dwie minuty. Dzień wcześniej nie zajrzałem do nich wcale, bo słowa „błąd połączenia” wskazują inny kierunek: router, zasięg, chwilową niedostępność cudzego serwera. Przy takiej diagnozie człowiek czeka, aż samo przejdzie, i próbuje jeszcze raz. Stąd piętnaście prób.

66 znaków, z czego 39 to forma prawna

Zamówienie złożyła spółka komunalna, jedna z tych, których nazwa własna jest opisem działalności. Sama nazwa ma 26 znaków. Po niej stoi spacja i „spółka z ograniczoną odpowiedzialnością”, czyli kolejnych 39 znaków ze spacjami. Razem 66. Ktoś, kto wypełniał formularz w sklepie, przepisał nazwę tak, jak figuruje w rejestrze i jak ma stać na fakturze. Zrobił to poprawnie.

Limit 50 znaków na nazwę odbiorcy nie jest naszym wymysłem. Zwrócił go interfejs brokera kurierskiego, przez którego panel zamawia kurierów różnych firm. Skąd akurat 50, nie wiem i nie będę zgadywał. Etykieta na paczce ma skończoną szerokość, a systemy przewoźników powstawały w czasach, gdy pola tekstowe projektowano oszczędnie, ale to moje przypuszczenie, nie informacja od brokera.

Wiem natomiast, jak łatwo ten limit przekroczyć polską nazwą. Sama fraza „spółka z ograniczoną odpowiedzialnością spółka komandytowa” ma 58 znaków. Firma o takiej formie prawnej nie mieści się w polu odbiorcy, zanim ktokolwiek wpisze jej nazwę własną. Podobnie jest ze szkołami z patronem i miejscowością w nazwie, z samodzielnymi publicznymi zakładami opieki zdrowotnej, ze stowarzyszeniami, które w nazwie mają cel statutowy. Sklep sprzedający firmom i instytucjom trafi na taką nazwę prędzej czy później. Nasz trafił po niecałych dwóch miesiącach od uruchomienia wysyłek z panelu.

Dlaczego dopiero wtedy? Wcześniejsze zamówienia miały nazwy, które mieściły się w polu, więc integracja przechodziła każdą próbę, jaką jej zafundowało życie. W spisie rzeczywistych błędów nadania, który zrobiliśmy w połowie października, były kraj, telefon, punkt odbioru, sposób nadania i brak środków na koncie. Długości nazwy na tej liście nie było, bo jeszcze się nie zdarzyła. O limicie 50 znaków dowiedzieliśmy się od brokera w chwili, gdy go przekroczyliśmy, i to jest zarzut do nas, bo opis pól w dokumentacji trzeba przeczytać przed pierwszą wysyłką.

Skąd na ekranie wzięły się słowa o połączeniu?

Broker odpowiedział precyzyjnie. Podał pole i podał limit. Po drodze do magazyniera ta informacja zniknęła i warto prześledzić, w których miejscach mogła zniknąć, bo żadne z nich nie jest egzotyczne.

Pierwsze miejsce to przeglądarka. Ekran zamówienia wysyła do serwera prośbę o nadanie i czeka na odpowiedź w formacie JSON. Jeżeli cokolwiek pójdzie inaczej, niż zakładał programista, czyli zabraknie sieci, upłynie czas albo przyjdzie odpowiedź, której nie da się odczytać jako JSON, kod wpada w tę samą gałąź i pokazuje czerwony pasek z napisem „Błąd połączenia”. Policzyłem przy okazji, ile razy ten napis występuje w szablonach panelu: 67 razy w 18 plikach, z tego 16 razy na samym ekranie zamówienia. Wszędzie pełni tę samą rolę worka na wszystko, czego autor kodu nie przewidział.

To częsty wzorzec i ma swoje źródło w tym, jak działa przeglądarka. Funkcja `fetch`, którą strony pobierają dane, nie traktuje kodu błędu z serwera jako porażki. Odrzuca żądanie tylko wtedy, gdy sieć naprawdę zawiodła. Programista dopisuje więc własną obsługę i jeśli robi to jednym „złap wszystko”, to awaria sieci, błąd serwera i nieczytelna odpowiedź dostają ten sam podpis.

Drugie miejsce to kod odpowiedzi serwera. Gdy broker odrzucał nadanie, nasz panel odpowiadał przeglądarce kodem 502. Ten kod znaczy, że serwer pośredniczący dostał od serwera, z którym rozmawiał, nieprawidłową odpowiedź. Tymczasem odpowiedź brokera była jak najbardziej prawidłowa, tyle że odmowna i dotycząca danych. Dla takiej sytuacji protokół ma inny kod, 422, oznaczający poprawnie zbudowane żądanie z treścią, której nie da się przetworzyć. Różnica wygląda na akademicką, dopóki między serwerem a przeglądarką nie stanie coś, co kody z rodziny 500 traktuje po swojemu, albo dopóki ktoś nie zacznie liczyć „awarii” na podstawie samych kodów.

Którą z tych dróg napis trafił na ekran w tamtą środę i czwartek, nie odtworzyłem. Mam zgłoszenie z magazynu, w którym stoją słowa „błąd połączenia”, mam kod, w którym te słowa są podpisem każdej nieodczytanej odpowiedzi, i mam dziennik, w którym stoi prawdziwa przyczyna. Po wdrożeniu poprawki zamówienie przeszło i odtwarzanie ścieżki błędu zeszło na dalszy plan. Dziś uważam to za drugie zaniedbanie w tej historii, mniejsze od pierwszego, ale tego samego rodzaju: skoro objaw zniknął, przestałem pytać.

Dziesięć minut od zgłoszenia do wdrożenia

O 14:32 nowa wersja panelu działała na serwerze. Zmiana to jedna funkcja na kilkanaście linii, wstawiona w miejscu, gdzie panel buduje dane odbiorcy dla brokera. Robi trzy rzeczy w ustalonej kolejności.

Jeśli nazwa mieści się w 50 znakach, funkcja niczego nie rusza. To ważniejsze, niż wygląda. Skracanie wszystkiego jak leci zmieniłoby etykiety setek paczek, przy których nigdy nie było problemu.

Najpierw forma prawna

Gdy nazwa jest za długa, funkcja szuka w niej pełnego brzmienia formy prawnej i podmienia je na skrót. „Spółka z ograniczoną odpowiedzialnością” staje się „Sp. z o.o.”, spółka akcyjna „S.A.”, komandytowa „Sp.k.”, jawna „Sp.j.”. Wzorce nie zwracają uwagi na wielkość liter i dopuszczają zapis bez polskich znaków, bo formularze sklepowe widziały już wszystko.

Te cztery skróty nie są naszą inwencją. Kodeks spółek handlowych wprost dopuszcza ich używanie w obrocie: art. 160 § 2 dla spółki z o.o., art. 305 § 2 dla akcyjnej, art. 104 § 2 dla komandytowej i art. 24 § 2 dla jawnej. Nazwa na etykiecie pozostaje więc nazwą tej samej firmy, zapisaną w sposób przewidziany przez ustawę. W naszym przypadku z 66 znaków zrobiło się 37 i na tym funkcja skończyła pracę.

Piąty wzorzec na liście to „stowarzyszenie” zamieniane na „Stow.”. Tu ustawowego skrótu nie ma, to nasz kompromis, żeby z nazwy organizacji zostało na etykiecie jak najwięcej tego, co ją odróżnia od innych.

Potem cięcie na granicy słowa

Jeżeli po podmianie nazwa nadal ma ponad 50 znaków, funkcja obcina ją do pięćdziesiątego znaku i cofa się do ostatniej spacji, żeby na etykiecie nie zostało urwane pół wyrazu. Kurier, który czyta „Szkoła Podstawowa nr 3 im. Marii”, wie, dokąd idzie. Kurier, który czyta „Szkoła Podstawowa nr 3 im. Marii Skłodowskiej-Cu”, też trafi, ale paczka wygląda jak nadana przez zepsuty system.

Tę samą technikę stosujemy w tym projekcie w dwóch innych miejscach. Drukarka fiskalna ma krótkie pole na nazwę towaru i nazwy pozycji paragonu są przycinane do pełnego słowa. Generator tekstów reklamowych w innym naszym produkcie tnie hasła do limitów platform tak samo. Za każdym razem powód jest ten sam: cudzy system ma sztywne pole, a nasze dane powstały bez wiedzy o nim.

Czego ta funkcja nie umie

Lista form prawnych ma pięć pozycji. Nie ma na niej spółki partnerskiej, komandytowo-akcyjnej, fundacji, spółdzielni ani samodzielnego publicznego zakładu opieki zdrowotnej, którego sama nazwa rodzajowa ma 46 znaków. Takie nazwy trafią od razu do cięcia.

Samo cięcie ma drobną wadę, którą zauważyłem dopiero przy pisaniu tego tekstu. Gdy pięćdziesiąty znak wypada dokładnie na końcu słowa, funkcja i tak cofa się do poprzedniej spacji i gubi jedno słowo, które by się zmieściło. Paczka dojdzie, bo adres i telefon są w osobnych polach. Wada polega na tym, że napisałem „na granicy słowa”, a w jednym przypadku granica jest o słowo za wcześnie.

Funkcja nie wie też, co w nazwie jest ważne. Przy długiej nazwie szkoły ucina koniec, a na końcu bywa miejscowość. Dla kuriera to bez znaczenia, bo miejscowość ma w adresie, ale dla portiera w dużym budynku liczy się czasem właśnie to, co wypadło.

Po wdrożeniu agent sprawdził skutek na tym konkretnym zamówieniu: zapytanie o wycenę zwróciło 21 ofert kurierskich, a w danych odbiorcy stała nazwa ze skrótem. Dopiero wtedy poszła odpowiedź do magazynu, że można nadawać.

Dlaczego nie kazałem magazynowi skracać nazw ręcznie?

Najprostsza poprawka wyglądałaby inaczej. Wystarczyło pokazać na ekranie zdanie „nazwa odbiorcy jest za długa, skróć ją do 50 znaków” i zostawić resztę człowiekowi. Komunikat byłby poprawny, zrozumiały i mówiłby, co zrobić.

Odrzuciłem to z dwóch powodów. Pierwszy: magazynier edytowałby dane zamówienia, a te same dane służą do faktury. Na fakturze chcę mieć nazwę w brzmieniu z rejestru, na etykiecie wersję, która mieści się w polu przewoźnika. Skracanie w zamówieniu psułoby jedno, żeby naprawić drugie, i po miesiącu mielibyśmy w bazie klientów nazwy poprzycinane według uznania osoby, która akurat pakowała.

Drugi powód jest ogólniejszy. Jeżeli system potrafi sam poprawić dane w sposób przewidywalny i bez utraty sensu, komunikat o błędzie jest zbędny. Człowiek przy taśmie klejącej nie powinien liczyć znaków. Komunikat zostawiam na sytuacje, w których potrzebna jest decyzja: brak telefonu odbiorcy, paczkomat nieobsługiwany przez wybraną usługę, puste konto u brokera. Tam nikt za magazyniera nie zgadnie i tam zdanie na ekranie musi go poprowadzić.

Była jeszcze trzecia możliwość, czyli walidacja w sklepie, przy składaniu zamówienia. Formularz mógłby nie przyjąć nazwy dłuższej niż 50 znaków. Uważam to za najgorszy wariant, bo ograniczenie jednego z naszych dostawców stawałoby się kłopotem klienta, który chce zapłacić. W dodatku dotyczyłoby także zamówień z odbiorem osobistym, przy których żaden przewoźnik nie bierze udziału.

Zostało więc skracanie w jednym punkcie, na styku z brokerem, tuż przed wysłaniem danych. Zamówienie w bazie ma nadal pełną nazwę, a wersję skróconą dostaje wyłącznie przewoźnik.

Słownik komunikatów, który zgubił liczbę 50

Ta część jest dla mnie najmniej wygodna, bo dwa tygodnie przed opisaną awarią byłem przekonany, że temat komunikatów w tym panelu mamy załatwiony.

W połowie października wysyłka stanęła na innym zamówieniu. W polu kraju stało słowo „Polska”, a panel brał z niego dwie pierwsze litery jako kod kraju i wysyłał brokerowi „PO”. Broker odrzucił nadanie dziewięć razy, zanim sprawa do nas dotarła. Na dodatek w jego odpowiedzi stało „kraj nadawcy”, choć błędny był kraj odbiorcy, więc nawet ktoś, kto przeczytał komunikat uważnie, szukał problemu w ustawieniach sklepu zamiast w zamówieniu.

Poprawiliśmy wtedy kod kraju i dołożyłem jedno wymaganie: komunikaty z brokera mają docierać do magazyniera jako zdania zrozumiałe dla laika. Powstał słownik, który rozbiera odpowiedź brokera na pole i problem, a potem składa z tego okno z trzema częściami: co się stało, co poprawić i gdzie, co zrobić dalej. Oryginalny tekst zostaje pod spodem, drobnym drukiem, dla administratora. Słownik zna ponad trzydzieści pól i kilkanaście typowych sformułowań. Ma też wpis dla sytuacji nieznanej, z prośbą o zdjęcie okna i wysłanie go administratorowi. Byłem z niego zadowolony.

Przy pisaniu tego tekstu sprawdziłem, co ten słownik robi ze zdaniem „Nazwa odbiorcy: Maksymalnie 50 znaków”. Pole rozpoznaje poprawnie. Problem dopasowuje po fragmencie „maksymaln” i tłumaczy jako „za duża wartość”. Okno mówi więc magazynierowi: „Za duża wartość: imię i nazwisko / nazwa klienta, popraw w zamówieniu, w sekcji Dane wysyłki”.

Kierunek jest właściwy, bo wskazuje pole. Tyle że „za duża wartość” przy nazwie firmy nic nie znaczy, a jedyna informacja, która pozwala naprawić sprawę w pół minuty, czyli liczba 50, wypadła. Oryginał mówił, ile znaków wolno. Nasze tłumaczenie „po ludzku” mówiło mniej niż oryginał. Wzorzec „maksymalnie” pisałem z myślą o wadze i wymiarach paczki, gdzie „za duża wartość” pasuje, i nie przyszło mi do głowy, że broker tym samym słowem opisuje długość tekstu. W chwili pisania tego wpisu ta linijka słownika wygląda tak samo. Automat skraca nazwy, więc akurat ten komunikat nie ma już okazji się pojawić, ale inne pola tekstowe też mają limity, a słownik potraktuje je identycznie.

Wniosek z tej kontroli dotyczy każdej warstwy tłumaczącej cudze błędy: tłumaczenie nie może gubić liczb ani nazw pól z oryginału. Jeśli broker podał „50”, to „50” ma być w zdaniu dla użytkownika. Podobną pomyłkę, tylko w drugą stronę, mieliśmy przy flocie pojazdów, gdzie warunek dopasowujący fragment słowa złapał więcej, niż powinien. Dopasowanie po kawałku tekstu jest wygodne i w obu przypadkach zrobiło coś innego, niż miałem na myśli.

Cztery pytania do każdego komunikatu o błędzie

Dyspozytor w firmie kurierskiej, który dzwoni do nadawcy z informacją „paczka nie wyjechała”, usłyszy natychmiast: dlaczego i co mam zrobić. Nikt nie przyjąłby od niego odpowiedzi „wystąpił błąd operacji”. Od ekranu przyjmujemy ją codziennie.

Do oceny komunikatów w panelu używam teraz czterech pytań i żadne z nich nie jest moje. Tę samą listę, innymi słowami, podaje od lat Nielsen Norman Group, a wytyczne dostępności WCAG w kryterium 3.3.3 wymagają, by system podał użytkownikowi sugestię poprawki, jeśli ją zna.

  1. Co się nie udało, nazwane czynnością użytkownika. „Nie udało się nadać paczki” zamiast „błąd 502”.
  2. Po czyjej stronie leży przyczyna. Dane zamówienia, ustawienia sklepu, broker, sieć. Od tego zależy, czy człowiek ma coś poprawić, czy poczekać, czy zadzwonić.
  3. Co zrobić teraz, jednym zdaniem w trybie rozkazującym. „Skróć nazwę do 50 znaków”, „doładuj konto”, „wybierz inną usługę”.
  4. Co przekazać dalej, jeśli nie pomoże. Numer zamówienia i oryginalna treść błędu, do skopiowania jednym kliknięciem.

Komunikat „Błąd połączenia” nie odpowiada na żadne z nich, a na drugie odpowiada fałszywie, bo wskazuje sieć. Oryginał brokera odpowiadał na drugie i trzecie. Nasze okno ze słownika odpowiadało na pierwsze, drugie i połowę trzeciego.

Jest też strona serwerowa tej samej sprawy. Żeby ekran mógł pokazać dobre zdanie, serwer musi mu przekazać błąd w postaci, którą da się rozebrać: jaki to rodzaj problemu, którego pola dotyczy, jaki jest limit. Istnieje na to standard, RFC 9457 z lipca 2023 r., opisujący jednolity format szczegółów problemu w odpowiedziach API. Nie wdrożyliśmy go w tym panelu i nie twierdzę, że każdy mały system powinien. Sama zasada wystarczy: błąd, który da się przewidzieć, ma własny typ i własne pola, a nie jedno zdanie tekstu, które każda kolejna warstwa interpretuje po swojemu.

Ostatnia rzecz dotyczy worka na resztę. Każdy system potrzebuje komunikatu na sytuację, której nikt nie przewidział. Powinien on mówić prawdę, czyli „nie wiem, co się stało”, i od razu podawać to, co wiadomo: godzinę, numer zamówienia, treść odpowiedzi serwera, jeśli jakaś przyszła. Napis „błąd połączenia” w tej roli zgaduje przyczynę, a magazynier nie ma jak odróżnić zgadywania od diagnozy.

Ile kosztowały dwa słowa na czerwonym pasku?

Policzmy to, co da się policzyć. Jedna paczka wyszła z opóźnieniem ponad doby. Odbiorcą była instytucja, która zamówiła sprzęt i za niego zapłaciła. Prób nadania było piętnaście na przestrzeni dwóch dni, każda z wyborem usługi i potwierdzeniem. Ja straciłem w środę czas na szukanie przyczyny bez skutku. W czwartek sprawa przeszła jeszcze przez kolejną osobę, zanim trafiła do nas w formie, którą dało się obsłużyć. Sama naprawa zajęła dziesięć minut i jest najtańszą pozycją na tej liście.

Kwoty z tego nie złożę, bo to sklep klienta, a strat w zaufaniu odbiorcy nie umiem wycenić. Mogę za to wskazać, co kosztowało najwięcej czasu: droga informacji. Odpowiedź brokera przyszła w ułamku sekundy przy pierwszej próbie. Do osoby, która mogła coś z nią zrobić, szła ponad 24 godziny, przez ekran, magazyniera, kolejną osobę i wiadomość tekstową, tracąc po drodze treść.

Druga rzecz to cisza po naszej stronie. Piętnaście identycznych odmów dla jednego zamówienia nie uruchomiło żadnego powiadomienia. Panel sumiennie zapisywał każdą z nich i nikomu o tym nie mówił. Mamy w tym projekcie metryki dla synchronizacji ze sklepem i dla kosztów magazynowych, a nieudane nadania zostawały w dzienniku, do którego nikt nie zagląda bez powodu. To ten sam rodzaj ślepoty, który opisałem przy CRM, gdzie monitoring sprawdzał, czy serwer odpowiada, i przez trzy miesiące nie zauważył, że nikt się nie loguje. Serwer panelu działał bez zarzutu. Nie działała jedna czynność dla jednego zamówienia, a tego żadna sonda nie mierzyła.

Reguła, którą z tego wyprowadziłem, jest krótka: trzecia identyczna odmowa dla tego samego zamówienia ma wysłać wiadomość do nas, razem z treścią odmowy. Przy trzeciej próbie mielibyśmy zdanie o 50 znakach w skrzynce w środę rano. Człowiek, który klika trzeci raz to samo i dostaje to samo, już wie, że samo nie przejdzie, tylko nie ma komu tego powiedzieć w sposób, który zawiera przyczynę.

Jest w tym jeszcze obserwacja o ludziach, którą powtarzam sobie przy każdym takim przypadku. Magazynier zgłosił dokładnie to, co widział. Zgłoszenie „błąd połączenia” było rzetelne. Nierzetelny był ekran.

Limity cudzych systemów w zamówieniu na oprogramowanie

Każda integracja ma po drugiej stronie pola o ustalonej długości i dozwolonych znakach. Broker kurierski ma limit na nazwę odbiorcy, drukarka fiskalna na nazwę towaru, platforma reklamowa na nagłówek. System księgowy, bank i bramka SMS mają swoje. Te liczby są w dokumentacjach, zwykle w tabelach, których nikt nie czyta, bo przykładowe zapytanie z dokumentacji działa od pierwszego razu.

Wniosek dla specyfikacji każdej następnej integracji to jedna tabela: pole po naszej stronie, pole po stronie dostawcy, limit długości, dozwolone znaki i decyzja, co robimy, gdy nasze dane się nie mieszczą. Możliwości są trzy. Skracamy automatycznie według opisanej reguły, zatrzymujemy operację z komunikatem dla człowieka albo nie dopuszczamy takich danych na wejściu. Dla każdego pola wybiera się jedną i zapisuje dlaczego. Przy brokerze kurierskim taka tabela ma kilkanaście wierszy i powstaje w godzinę. W październiku jej nie mieliśmy, więc decyzję za nas podjął przypadek: operacja się zatrzymała, a komunikat trafił w worek.

Jeśli zamawiasz oprogramowanie w firmie zewnętrznej, możesz o tę tabelę zwyczajnie poprosić. Odpowiedź „nie mamy czegoś takiego” jest informacją o tym, jak wykonawca podchodzi do integracji. Możesz też zadać pytanie prostsze, które sprawdza to samo od strony użytkownika: co zobaczy twój pracownik, gdy system dostawcy odrzuci dane? Dobry wykonawca pokaże ekran. Słaby powie, że to się nie zdarza.

Do testów odbiorczych powinien trafić zestaw danych, które mają być niewygodne: najdłuższą nazwę firmy, jaką znajdę w rejestrze, nazwisko dwuczłonowe z myślnikiem, adres z numerem lokalu po ukośniku, miejscowość z kreską i dopiskiem gminy, telefon z prefiksem kraju i ze spacjami. Żadna z tych rzeczy nie jest rzadka w polskich danych. W tym samym sklepie wcześniej wyszło, że faktura liczona z cen katalogowych rozjechała się z kwotą zapłaconą, bo nikt nie sprawdził zamówienia z kuponem. Mechanizm był identyczny: system działał poprawnie na danych, które przyszły nam do głowy.

Nazwa na 66 znaków była w tym sklepie pierwsza, a dłuższych w rejestrach nie brakuje. Następna, która trafi do tego panelu, zostanie skrócona bez udziału człowieka i nikt jej nie zauważy. O tym, co panel zrobi z następnym limitem, którego jeszcze nie znamy, zdecyduje zdanie w worku na nieznane błędy, i to zdanie mam teraz do przepisania.

Najczęstsze pytania

Ile znaków może mieć nazwa odbiorcy na liście przewozowym?

Zależy od przewoźnika i od pośrednika, przez którego nadajesz. Broker, z którego korzysta opisany sklep, przyjmuje w polu nazwy odbiorcy najwyżej 50 znaków i odrzuca dłuższe dane w całości. Limity dla swojego dostawcy znajdziesz w dokumentacji jego interfejsu, przy opisie pól adresowych.

Czy na etykiecie kurierskiej można wpisać „sp. z o.o.” zamiast pełnej formy prawnej?

Tak. Kodeks spółek handlowych w art. 160 § 2 dopuszcza używanie w obrocie skrótu „sp. z o.o.”, a analogiczne przepisy dotyczą spółki akcyjnej, komandytowej i jawnej. Na fakturze i w umowie warto zostawić nazwę w brzmieniu z rejestru, na etykiecie skrót niczego nie zmienia.

Dlaczego system pokazuje „błąd połączenia”, skoro internet działa?

W wielu aplikacjach ten napis jest podpisem każdej sytuacji, której programista nie przewidział: braku sieci, przekroczenia czasu, błędu serwera albo odpowiedzi w nieoczekiwanym formacie. Prawdziwa przyczyna zwykle jest zapisana w dzienniku serwera. Jeśli komunikat wraca przy tej samej czynności i tych samych danych, a inne czynności działają, problem prawie na pewno leży w danych, a nie w sieci.

Jak powinien wyglądać dobry komunikat o błędzie dla pracownika?

Powinien nazwać czynność, która się nie udała, wskazać, po czyjej stronie leży przyczyna, i powiedzieć jednym zdaniem, co zrobić. Jeśli system dostawcy podał konkretną liczbę albo nazwę pola, mają one trafić do komunikatu bez zmian. Treść techniczną warto zostawić pod spodem, do skopiowania dla administratora.

Czy lepiej automatycznie poprawiać dane, czy pokazywać błąd?

Automatyczna poprawka ma sens, gdy jest przewidywalna, nie zmienia znaczenia danych i dotyczy tylko jednego odbiorcy, tak jak skrót formy prawnej na etykiecie. Gdy potrzebna jest decyzja człowieka, na przykład przy braku telefonu albo niedostępnej usłudze, system powinien się zatrzymać i powiedzieć, co poprawić. Poprawiania danych źródłowych, z których korzystają też faktury i umowy, automatowi bym nie oddawał.

Źródła

Liczby dotyczące awarii, czyli 15 odmów, 66 i 50 znaków oraz godziny zgłoszenia i wdrożenia, pochodzą z dziennika serwera i notatki z naprawy z 29.10.2026. Liczba wystąpień napisu „Błąd połączenia” w szablonach panelu to wynik przeszukania kodu z 22.11.2026.

Słownik pojęć

  • Broker kurierski - pośrednik, przez którego jeden system zamawia przesyłki u wielu przewoźników i dostaje etykiety oraz statusy.
  • API - interfejs, przez który programy wymieniają dane bez udziału człowieka; tutaj panel sklepu wysyła nim dane paczki do brokera.
  • Dziennik serwera (log) - plik, w którym system zapisuje kolejne zdarzenia, w tym błędy, z datą i szczegółami.
  • Kod odpowiedzi HTTP - trzycyfrowa liczba, którą serwer informuje o wyniku żądania; kody 4xx oznaczają problem z żądaniem, 5xx problem po stronie serwera.
  • JSON - tekstowy format danych używany w komunikacji między przeglądarką a serwerem.
  • Walidacja - sprawdzenie danych pod kątem reguł, na przykład długości albo formatu, zanim zostaną użyte.
  • Forma prawna - część nazwy firmy określająca jej rodzaj, na przykład spółka z ograniczoną odpowiedzialnością.

Który napis w twoim systemie znaczy „coś poszło nie tak”?

Zapytaj osobę, która w twojej firmie najczęściej klika w systemie zamówień albo w programie magazynowym, jaki komunikat o błędzie widzi najczęściej i co wtedy robi. Odpowiedź „klikam jeszcze raz” oznacza, że masz własną wersję tej historii, tylko jeszcze bez daty. A gdy z takiej rozmowy wyjdzie jeden konkretny ekran, z którym nie wiadomo, co począć, to jest dobry temat na rozmowę o jednym problemie: zasady opisałem na stronie współpracy, a adres to [email protected].

✓ Sprawdzone na
własnej firmie
cybulski.ai JC
You've successfully subscribed to cybulski.ai
Great! Next, complete checkout for full access to cybulski.ai
Welcome back! You've successfully signed in.
Unable to sign you in. Please try again.
Success! Your account is fully activated, you now have access to all content.
Error! Stripe checkout failed.
Success! Your billing info is updated.
Error! Billing info update failed.