Proszę ustalić budżet czasowy całego procesu, ustawić timeout zarówno dla połączenia, jak i odpowiedzi, ponawiać tylko bezpieczne błędy tymczasowe z wykładniczym odstępem i losowym rozrzutem, respektować limit dostawcy i idempotentność, a po wyczerpaniu prób przenieść zadanie do widocznego stanu wymagającego naprawy.
Integracja API musi uwzględniać powolną odpowiedź, chwilową niedostępność oraz limit liczby wywołań. Bez timeoutu jedno połączenie może blokować procesy robocze i zasoby. Bez kontrolowanego ponawiania chwilowy błąd zamienia się w utratę danych. Zbyt agresywne ponawianie obciąża jednak osłabioną usługę i wywołuje lawinę żądań, która wydłuża awarię.
Odporność wynika z połączenia rozsądnego budżetu czasowego, rozróżniania błędów, idempotencji, rosnących odstępów, losowego rozrzutu i kolejki. Wartości nie da się uniwersalnie skopiować. Muszą wynikać z procesu użytkownika, kontraktu dostawcy, wolumenu i skutków opóźnienia. Każdy mechanizm wymaga monitoringu i progu, po którego przekroczeniu interweniuje człowiek.
Wyznacz timeout na podstawie całego procesu użytkownika
Najpierw należy ustalić, jak długo może czekać użytkownik lub system zależny. Ten budżet trzeba podzielić między DNS, połączenie, transfer, przetwarzanie i ewentualne ponowienia. Timeout klienta nie powinien być dłuższy niż czas, po którym usługa nadrzędna i tak anuluje żądanie. W przeciwnym razie trwa niepotrzebna praca, której wyniku nikt nie odbierze.
Należy rozróżniać czas nawiązania połączenia i czas odczytu odpowiedzi. Długi eksport może zasadnie trwać dłużej niż prosta weryfikacja. Jeśli operacja przekracza budżet interaktywny, należy zamienić ją na zadanie asynchroniczne ze stanem. Nie należy zwiększać timeoutu bez diagnozy; może to jedynie ukryć przeciążenie lub zablokowany proces.
Klasyfikuj błędy przed ponowieniem
Tymczasowy błąd sieci, przeciążenie lub niektóre odpowiedzi serwera mogą kwalifikować się do ponowienia. Nieprawidłowe dane wejściowe, brak uprawnień lub nieistniejący zasób zwykle nie zmienią się przy kolejnej próbie. Konkretne reguły należy ustalać na podstawie kontraktu API i treści błędu, a nie tylko szerokiej grupy kodów statusu.
W przypadku operacji zapisu należy zweryfikować idempotencję jeszcze przed włączeniem ponawiania. Timeout nie oznacza, że serwer nie wykonał operacji. Powtórzona płatność lub zamówienie może mieć większe skutki niż pierwotna awaria. Jeśli API nie zapewnia bezpiecznego mechanizmu, należy zastosować weryfikację stanu lub kontrolę ręczną zamiast ślepego ponawiania.
- błąd tymczasowy z realną szansą na odzyskanie
- operacja idempotentna lub możliwa do bezpiecznej weryfikacji
- ograniczona liczba prób i łączny wiek
- widoczny wynik po ostatecznym niepowodzeniu
Stosuj odstępy, losowe rozproszenie i przestrzegaj limitów zapytań
Między próbami zwiększaj odstęp i dodawaj losowy rozrzut, aby wszyscy klienci nie ponowili wywołania w tym samym momencie. Ustal górny limit czasu i liczby prób. Jeśli dostawca zwraca informację o następnym dozwolonym terminie lub pozostałym limicie, przetwarzaj ją zgodnie z dokumentacją i współdziel budżet między workerami.
Limity zapytań (rate limit) należy monitorować na poziomie konta, endpointu lub użytkownika, zależnie od modelu usługi. Równolegle działające procesy robocze wymagają koordynacji, w przeciwnym razie każdy zakłada, że ma do dyspozycji pełną przepustowość. Operacje krytyczne należy traktować priorytetowo względem importu wsadowego. Cache lub endpoint zbiorczy mogą zmniejszyć liczbę wywołań, jeśli zachowują poprawność i aktualność danych.
Oddziel żądanie użytkownika od kolejki
Jeśli zewnętrzne API nie jest potrzebne do natychmiastowej odpowiedzi, należy zapisać zamiar i przetworzyć go w kolejce. Użytkownik otrzymuje potwierdzenie przyjęcia, a nie fałszywą obietnicę realizacji. Kolejka pozwala ograniczyć współbieżność, ponawiać próby przy błędach tymczasowych i zachować zadanie podczas awarii. Każdy komunikat potrzebuje stałej tożsamości i maksymalnego czasu ważności.
Po wyczerpaniu prób zadanie należy przenieść do kwarantanny wraz z przyczyną i bezpiecznym sposobem naprawy. Nieskończone ponawianie (retry) zużywa zasoby i maskuje trwały błąd danych. Przy dłuższej awarii mechanizm ochronny może tymczasowo wstrzymać wywołania i regularnie sprawdzać, czy usługa wróciła do działania. Nie może jednak pozostać wyłączony bez alarmu.
Monitoruj wynik techniczny i biznesowy
Proszę monitorować opóźnienia, timeouty, liczbę prób, odpowiedzi o przekroczeniu limitu, wiek kolejki oraz odsetek zadań w kwarantannie. Metryki należy podzielić według dostawcy i operacji. Średni czas może ukrywać długi ogon, który wpływa na klientów. Alert potrzebuje właściciela, progu i procedury, a nie tylko surowego błędu.
Sukces techniczny nie oznacza kompletnego procesu. Warto porównywać liczbę przyjętych zamówień, eksportów lub dokumentów z oczekiwanym przepływem. Po zmianie limitu lub klienta należy przeprowadzić test obciążeniowy i regresyjny w dozwolonym środowisku. Plan pojemności trzeba aktualizować wraz ze wzrostem wolumenu, a nie dopiero po pierwszej masowej awarii.
- wiek najstarszej oczekującej operacji
- liczba prób w zależności od typu błędu
- wykorzystanie limitu według klienta i endpointu
- obiekty biznesowe brakujące w systemie docelowym
- czas odzyskiwania po zwolnieniu zewnętrznej przepustowości
- wpływ zadań wsadowych na krytyczne wywołania
Najczęstsze pytania
Ile razy należy ponowić żądanie API?
Uniwersalna liczba nie istnieje. Zależy od budżetu czasowego, typu błędu, idempotencji, limitów i wpływu biznesowego. Po przekroczeniu granicy musi powstać widoczny stan naprawczy, a nie ciche odrzucenie.
Czy dłuższy timeout jest bezpieczniejszy?
Nie automatycznie. Długi timeout wiąże zasoby i może przekroczyć czas procesu nadrzędnego. Najpierw należy zdiagnozować opóźnienia, a przy długotrwałej pracy zastosować model asynchroniczny z zapisem stanu.
Co zrobić po przekroczeniu limitu zapytań (rate limit)?
Należy respektować wytyczne dostawcy, zatrzymać agresywne ponawianie, rozłożyć żądania w czasie i sprawdzić współbieżność. Długoterminowo warto ograniczyć zbędne wywołania, używać partii lub uzgodnić odpowiednią przepustowość.
Źródła i dalsza lektura
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
