Jak zaplanować obsługę błędów API w sposób niezawodny

Zamówienie w sklepie internetowym dociera, ale system zarządzania zapasami nie odpowiada. Klient otrzymuje potwierdzenie, ale zamówienie nie pojawia się na liście zadań magazynu. Dwie godziny później kolega próbuje to odtworzyć z arkusza kalkulacyjnego, a następnie ręcznie rejestruje dane. To nie jest prosta usterka techniczna: może prowadzić do rozbieżności w zapasach, opóźnionej dostawy, błędnego fakturowania i utraty zaufania. Dlatego pytanie nie dotyczy tylko tego, jak zaprojektować obsługę błędów API, ale także jak utrzymać kontrolę nad procesem biznesowym w przypadku awarii systemu.

API zazwyczaj oznaczają połączenie między systemami. Łączą sklep internetowy z ERP, usługą transportową, systemem fakturowania, CRM lub aplikacją produkcyjną. Dopóki wszystkie odpowiedzi są szybkie i udane, to połączenie jest niewidoczne. W przypadku błędu okazuje się jednak, czy informacje rzeczywiście zostały przekazane, kto odpowiada za następny krok i czy istnieje sposób na bezpieczne kontynuowanie pracy.

Obsługa błędów zaczyna się od konsekwencji biznesowych

Pierwszym błędem w wielu organizacjach jest traktowanie wszystkich nieudanych wywołań API jako jednej kategorii. Istnieje jednak istotna różnica między sytuacją, gdy usługa kurierska jest niedostępna przez pięć sekund, a sytuacją, gdy łączymy się z systemem partnera z błędnym identyfikatorem lub gdy w zamówieniu brakuje kodu pocztowego dostawy.

Komunikat techniczny rzadko pomaga zespołowi operacyjnemu. „400 Bad Request” nie mówi, czy zamówienie można poprawić, ponownie wysłać, czy trzeba skonsultować się z klientem. „500 Internal Server Error” nie odpowiada, czy zamówienie zostało utracone, czeka na przetworzenie, czy zostało już utworzone w systemie docelowym, a tylko odpowiedź została utracona.

Zanim napiszemy zasady rozwoju, warto przeanalizować proces dla każdej ważnej integracji. Co inicjuje przekazywanie danych? Który system jest właścicielem danych? Co się dzieje, jeśli przekazanie się nie powiedzie? Kto to widzi, w jakim terminie i jak można sprawdzić poprawkę? Zamówienie, faktura czy instrukcja produkcyjna nie mogą stać się „danymi w stanie niepewności” tylko dlatego, że między dwoma systemami wystąpiła tymczasowa awaria komunikacji.

Jak zaprojektować obsługę błędów API dla każdego procesu?

Dobre projektowanie nie zaczyna się od jednej ogólnej listy błędów, ale od identyfikacji krytycznych zdarzeń biznesowych. Przekazywanie zamówienia w sklepie internetowym wymaga innej ochrony niż synchronizacja obrazu produktu. Przy tworzeniu faktury lub rezerwacji zasobów produkcyjnych nawet jedno zduplikowane żądanie może spowodować problemy finansowe lub operacyjne. Aktualizacja codziennego raportu zazwyczaj toleruje kilka minut opóźnienia, jeśli dokładność danych zostanie zachowana.

W każdym procesie warto zadać trzy pytania:

1. Jaki jest wpływ błędu na biznes, jeśli dane nie zostaną przekazane na czas?
2. Czy operację można powtórzyć bez szkodliwych skutków ubocznych?
3. Kiedy potrzebna jest decyzja ludzka, a kiedy sytuację można naprawić automatycznie?

Na podstawie odpowiedzi na te pytania można opracować proporcjonalną obsługę błędów. Nie każdy błąd wymaga natychmiastowego alarmu. Jeśli niekrytyczna aktualizacja danych dociera z trzyminutowym opóźnieniem, ciągłe powiadomienia telefoniczne generują raczej hałas. Jeśli jednak z powodu nieudanej rezerwacji zasobów sklep internetowy sprzedaje produkt, którego już nie ma w magazynie, potrzebna jest natychmiastowa i jednoznaczna reakcja.

Określone typy błędów

Błędy warto grupować nie tylko według kodów HTTP, ale także według sposobu obsługi. Do tymczasowych błędów należą na przykład przerwy w sieci, przeciążony system partnerski lub przekroczony limit czasu. W takich przypadkach ponowne próby są zazwyczaj uzasadnione. Trwałe błędy, takie jak błędne uprawnienia lub zmienione połączenie API, nie zostaną rozwiązane przez powtórzenie. Wymagana jest tu interwencja techniczna.

Trzecią grupą są błędy danych biznesowych lub reguł. Może to być brakujący numer podatkowy, nieistniejący numer artykułu, zamknięty status zamówienia lub niedozwolona zniżka. Systemy muszą jasno informować odpowiedzialnego pracownika, co należy poprawić, gdzie i co się stanie po poprawce.

To rozróżnienie chroni zespół przed wysyłaniem tego samego błędnego zamówienia sto razy, podczas gdy inne, tymczasowo nieudane przekazywanie danych ginie w codziennych zadaniach.

Powtórzenia muszą mieć granice i zasady

Powtórzenie żądania API wydaje się oczywistym rozwiązaniem, ale nie zawsze jest bezpieczne. Jeśli system pomyślnie utworzył fakturę, a połączenie zostało przerwane przed odpowiedzią, ponowne wysłanie żądania może utworzyć drugą fakturę. To samo może się zdarzyć przy rejestracji zamówienia, żądaniu płatności lub generowaniu etykiety wysyłkowej.

Dlatego do krytycznych operacji potrzebny jest unikalny identyfikator. System odbiorcy musi rozpoznać, że ponowne żądanie dotyczy tego samego zdarzenia biznesowego i nie powinno być wykonywane ponownie. Nazywamy to działaniem idempotentnym. Z punktu widzenia zarządzania jest to proste: tymczasowy błąd nie powinien skutkować podwójną operacją finansową, magazynową lub komunikacyjną z klientem.

Należy również regulować czas powtórzeń. Kilkusekundowe, a następnie stopniowo dłuższe oczekiwanie jest w wielu przypadkach odpowiednie. Ciągłe, natychmiastowe powtórzenia mogą jednak dodatkowo obciążać wadliwy system i maskować prawdziwy problem. Po określonej liczbie prób przypadek powinien trafić na kontrolowaną listę oczekujących, a nie zniknąć w plikach dziennika.

Niech kolega nie będzie rozwiązywaczem problemów między systemami

W wielu firmach obsługa błędów integracji istnieje w rzeczywistości w głowie doświadczonego pracownika. Wie, którego e-maila szukać, w którym systemie ponownie uruchomić operację i które dane ręcznie zmodyfikować. To wydaje się szybkim rozwiązaniem, ale tworzy proces zależny od osoby. W przypadku urlopu, choroby lub wzrostu staje się to natychmiastowym ryzykiem.

Zarządzalny system nie pozostawia użytkownika samemu z komunikatem o błędzie technicznym. Dla odpowiedzialnej roli potrzebna jest lista zadań, na której widać dotknięty obiekt biznesowy - na przykład identyfikator zamówienia, partnera lub fakturę - przyczynę błędu, dotychczasowe próby i kolejny zalecany krok. Po naprawieniu błędu proces powinien być kontynuowany zgodnie z zasadami, najlepiej bez ręcznego kopiowania danych.

To nie oznacza, że każdy wyjątek musi być zautomatyzowany. Warunki dostawy zamówienia od ważnego klienta lub nietypowa partia produkcyjna mogą wymagać prawdziwej oceny ludzkiej. Celem jest, aby kolega podejmował decyzje, a nie szukał danych między systemami i wpisywał te same informacje w różnych miejscach.

Rejestrowanie i monitorowanie: potrzebne są dowody, nie przypuszczenia

Kiedy kierownik pyta, „czy to zamówienie przeszło?”, system musi dać jednoznaczną odpowiedź. Do tego potrzebny jest śledzony identyfikator, znacznik czasu, wynik żądania, stan przetwarzania i - tam, gdzie to uzasadnione - szczegółowy powód błędu dla każdej ważnej operacji API. Oczywiście dane osobowe, płatnicze lub inne wrażliwe nie powinny być rejestrowane bez kontroli.

Jednak sam dziennik nie jest modelem operacyjnym. Należy monitorować odsetek nieudanych wywołań, długość kolejek przetwarzania, pogorszenie czasów odpowiedzi i powtarzające się problemy z danymi biznesowymi. Jeśli ten sam numer artykułu partnera powoduje błąd co tydzień, to nie jest to jednorazowy incydent, ale problem z właścicielem danych lub procesem.

Warto również mierzyć, ile czasu upływa między wystąpieniem błędu a jego rozwiązaniem, ile zdarzeń biznesowych czeka na przetworzenie oraz ile razy konieczna jest interwencja ludzka. Te wskaźniki nie opisują tylko wydajności IT. Pokazują, jak przewidywalne jest przetwarzanie zamówień, działanie magazynu lub administracja finansowa.

Należy również przygotować się na błędy w relacjach partnerskich

Nie każde API jest połączone z własnym systemem. Przewoźnicy, dostawcy usług płatniczych, platformy dostawców i systemy klientów mogą być częścią procesu. W takich przypadkach dostępność, czas odpowiedzi, zmiana wersji i jakość danych częściowo zależą od zewnętrznego podmiotu.

Dobra architektura nie opiera się zatem na nieograniczonym zaufaniu. Określa limity czasowe, ogranicza powtarzające się żądania do wadliwego partnera i tam, gdzie proces biznesowy na to pozwala, oddziela natychmiastowe doświadczenie klienta od przetwarzania w tle. Na przykład zamówienie można zarejestrować wewnętrznie, nawet jeśli etykieta wysyłkowa zostanie wygenerowana później. Ale można to zrobić tylko wtedy, gdy jest jasne, kto i kiedy sprawdzi późniejsze spełnienie.

Zarządzanie zmianą również tutaj się wpisuje. Zmiana pól lub reguł zewnętrznego API prędzej czy później nastąpi. Dzięki wersjonowanym połączeniom, środowisku testowemu i kontrolowanemu wprowadzeniu zmiana pozostaje zadaniem planowanym, a nie awarią w poniedziałkowy poranek.

Dobra obsługa błędów API ostatecznie nie obiecuje, że błędy nigdy się nie zdarzą. Zapewnia, że w przypadku błędu stan procesu biznesowego pozostaje znany, kolejny krok jest jasny, a organizacja nie polega na rutynie jednej osoby lub ręcznych arkuszach kalkulacyjnych. Warto zastanowić się, w którym z obecnych połączeń systemowych nie byliby dziś w stanie udowodnić, co się stało po nieudanym przekazaniu danych?