Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Retry w automatyzacji: jak ponawiać zadania bez tworzenia duplikatów

Koperta na zapętlonej trasie prowadzącej do szuflady z jedną kopertą

Timeout nie mówi, że serwer niczego nie zrobił. Mówi tylko, że klient nie dostał odpowiedzi na czas. Jeśli automatycznie powtórzysz utworzenie zamówienia, wysłanie wiadomości albo zapis wpisu, możesz wykonać tę samą operację drugi raz.

Bezpieczne retry w automatyzacji wymaga dwóch decyzji: kiedy ponowić żądanie i jak rozpoznać, że ten sam zamiar został już zrealizowany. Pokażę oba mechanizmy oraz mały przykład z SQLite, który można sprawdzić bez korzystania z płatnego API.

Najtrudniejszy błąd: zapis się udał, odpowiedź zginęła

Wyobraź sobie taki przebieg:

  1. Klient prosi o utworzenie raportu.
  2. Serwer zapisuje zadanie w bazie i zatwierdza transakcję.
  3. Połączenie urywa się przed dostarczeniem odpowiedzi.
  4. Klient widzi timeout i nie zna identyfikatora raportu.

Drugi request może stworzyć drugi raport, choć użytkownik zamawiał tylko jeden. Sam dłuższy timeout zmniejsza częstotliwość problemu, ale nie usuwa tej klasy awarii.

Dlatego przy operacjach zapisu trzeba rozróżnić wynik „na pewno odrzucone” od „nie wiadomo, czy wykonane”. Wprowadzenie do metod i odpowiedzi REST API pomaga ustalić podstawy, jednak o konkretnych gwarancjach rozstrzyga kontrakt endpointu.

Które błędy nadają się do ponowienia

Nie buduj pętli obejmującej każdy wyjątek. Błąd danych wejściowych nie zniknie po pięciu sekundach, a ponawianie bez uprawnień nie naprawi tokena.

Sytuacja Typowa decyzja Co sprawdzić
400 lub 422 Popraw dane, nie ponawiaj identycznego żądania w ciemno Format i reguły walidacji
401 lub 403 Zatrzymaj i ustal przyczynę Token, uprawnienia, ewentualny limit opisany przez API
429 Odczekaj według polityki usługi Retry-After i dostępny budżet
502, 503, 504 Rozważ ograniczone retry Czy operacja mogła już wywołać skutek
Timeout po wysłaniu danych Traktuj wynik jako niepewny Idempotencja lub możliwość sprawdzenia stanu

Tabela jest punktem wyjścia, nie zamiennikiem dokumentacji. Niektóre systemy używają 409 dla trwającego żądania o tym samym kluczu, inne dla trwałego konfliktu danych. Ponowienie ma sens tylko po rozpoznaniu tego znaczenia.

Obsługę nagłówków i ograniczania tempa opisuje osobno poradnik o rate limit API. Tutaj skupiamy się na skutku biznesowym operacji, a nie tylko na statusie HTTP.

Klucz idempotencji oznacza jeden zamiar

Klient tworzy trwały identyfikator operacji przed pierwszym wysłaniem. Każda próba realizacji tego samego zamiaru używa tego samego klucza i tej samej treści. Nowa świadomie zlecona operacja dostaje nowy identyfikator.

Przykładowo zapis „utwórz raport dla zamówienia 123” może mieć klucz powiązany z identyfikatorem tego zadania. Nie generuj nowego UUID wewnątrz pętli retry. Wtedy każda próba wyglądałaby dla serwera jak nowe zlecenie.

Po stronie odbiorcy potrzebny jest trwały rejestr: klucz, zakres użytkownika lub klienta, porównywana treść oraz wynik. Gdy klucz wraca z innymi danymi, serwer powinien zgłosić konflikt zamiast cicho zwrócić rezultat niepasującej operacji.

Nazwa nagłówka, czas przechowywania klucza i zachowanie przy błędach zależą od usługi. Stripe dokumentuje własny mechanizm kluczy idempotencji, ale samo dodanie podobnego nagłówka do dowolnego API niczego nie gwarantuje. Serwer musi go rzeczywiście obsługiwać.

Przykład: jeden zapis w SQLite mimo ponowienia

Poniższy kod tworzy zadanie oraz zapisuje jego klucz w jednej bazie i jednej transakcji. To demonstracja dla jednego lokalnego systemu, bez uwierzytelniania i bez zewnętrznych efektów, takich jak płatność czy wysłanie e-maila.

Zapisz go jako idempotency.py:

import json
import sqlite3
from contextlib import closing


def initialize(path):
    with closing(sqlite3.connect(path)) as db, db:
        db.executescript('''
        CREATE TABLE IF NOT EXISTS jobs (
          id INTEGER PRIMARY KEY, payload TEXT NOT NULL);
        CREATE TABLE IF NOT EXISTS requests (
          key TEXT PRIMARY KEY, payload TEXT NOT NULL,
          job_id INTEGER NOT NULL REFERENCES jobs(id));
        ''')


def create_job(path, key, payload):
    # One local database is the complete side effect in this example.
    encoded = json.dumps(payload, sort_keys=True, separators=(',', ':'))
    with closing(sqlite3.connect(path, timeout=5)) as db:
        db.execute('PRAGMA foreign_keys = ON')
        try:
            db.execute('BEGIN IMMEDIATE')
            previous = db.execute(
                'SELECT payload, job_id FROM requests WHERE key = ?',
                (key,)).fetchone()
            if previous:
                if previous[0] != encoded:
                    raise ValueError('Same key with a different payload')
                job_id = previous[1]
            else:
                cursor = db.execute(
                    'INSERT INTO jobs(payload) VALUES (?)', (encoded,))
                job_id = cursor.lastrowid
                db.execute('INSERT INTO requests VALUES (?, ?, ?)',
                           (key, encoded, job_id))
            db.commit()
            return {'job_id': job_id}
        except Exception:
            db.rollback()
            raise

BEGIN IMMEDIATE rozpoczyna transakcję zapisu przed sprawdzeniem klucza. SQLite dopuszcza jednego zapisującego naraz, dlatego równoległe próby nie przechodzą niezależnie przez ścieżkę „jeszcze nie istnieje”. Ograniczenie PRIMARY KEY dodatkowo wymusza unikalność klucza.

Cały efekt przykładu mieści się w tej transakcji. Zapis rekordu w jobs i rejestru w requests zatwierdzamy razem. Zamknięcie połączenia jest jawne, ponieważ kontekst transakcji sqlite3 nie jest tym samym co zamknięcie połączenia.

W osobnym pliku testowym uruchom:

from idempotency import initialize, create_job

initialize("demo.db")
first = create_job("demo.db", "report-123", {"period": "weekly"})
# Wyobraz sobie, ze odpowiedz first nie dotarla do klienta.
second = create_job("demo.db", "report-123", {"period": "weekly"})
assert first == second
print(second)

Obie próby zwracają identyfikator tego samego zadania. Ponowne użycie klucza z innym period zakończy się błędem. Kod używa parametrów zapytania, a nie sklejania treści użytkownika z SQL. Podstawy transakcji przypomina ściąga SQL, choć składnia i blokady różnią się między bazami.

W lokalnym teście sprawdzono też dwanaście równoległych wywołań z drugim wspólnym kluczem. Powstał jeden dodatkowy rekord. To test tego przykładu SQLite, nie deklaracja gwarancji dla dowolnego systemu rozproszonego.

Gdzie kończy się ochrona transakcji

Wyobraź sobie, że między zapisem do jobs a commit wywołujesz zewnętrzny serwer pocztowy. Baza może wycofać transakcję, lecz wysłanej wiadomości nie cofnie. Lokalny rejestr nie daje wtedy automatycznie gwarancji jednego dostarczenia.

Jednym z rozwiązań jest zapis zadania do wysłania razem z danymi biznesowymi, a następnie osobny proces dostarczający. Nadal trzeba obsłużyć powtórne dostarczenie do odbiorcy. Pomaga jego klucz idempotencji, unikalny identyfikator zdarzenia lub możliwość uzgodnienia stanu po awarii.

Nie obiecuj więc „exactly once” tylko dlatego, że dodałeś tabelę z kluczem. Określ granicę gwarancji: jedna transakcja bazy, przyjęcie przez API czy końcowy efekt u zewnętrznego odbiorcy. Każda granica wymaga osobnego rozumowania.

W systemie wieloużytkownikowym klucz powinien być powiązany z zaufanym identyfikatorem klienta. Publiczny endpoint nie może zwracać czyjegoś wyniku tylko dlatego, że inny użytkownik podał ten sam tekst klucza.

Backoff i jitter: kiedy wykonać kolejną próbę

Nawet bezpieczny zapis nie powinien być ponawiany bez przerwy. Zastosuj limit liczby prób i czasu całego zadania. Opóźnienie może rosnąć, na przykład według schematu 1, 2, 4 i 8 sekund, z maksymalnym pułapem. Są to parametry przykładu, nie zalecenie dla każdego dostawcy.

Jitter dodaje losowość, aby wiele procesów nie wracało jednocześnie po awarii. Jeśli serwer przekazał poprawny Retry-After, nie losuj czasu krótszego niż wymagana pauza. Gdy oczekiwanie nie mieści się w budżecie, odłóż zadanie zamiast utrzymywać nieskończoną pętlę.

Sprawdź też, czy biblioteka HTTP lub SDK nie ponawia już żądań. Trzy próby na poziomie klienta i trzy na poziomie całego workflow mogą dać dziewięć wywołań jednego kroku. Potrzebujesz jednego spójnego budżetu, nawet jeśli implementacja ma kilka warstw.

Retry pojedynczego kroku a restart całego workflow

Przepływ może kolejno utworzyć rekord, wygenerować plik i wysłać powiadomienie. Jeśli zawiedzie ostatni krok, ponowienie wszystkiego od początku wymaga ochrony każdego wcześniejszego efektu. Często lepiej zapisywać stan etapów i wznawiać od miejsca awarii.

W workflow n8n odróżnij obsługę błędu węzła od ręcznego ponowienia całego wykonania. Historia przebiegu ułatwia diagnozę, ale nie zastępuje trwałego klucza operacji po stronie systemu zapisującego dane.

Podobnie odbiornik webhooków powinien liczyć się z ponownym dostarczeniem zdarzenia. Identyfikator eventu od dostawcy jest przydatny do deduplikacji, jeśli jego zakres i stabilność są udokumentowane. Sam czas odebrania wiadomości nie identyfikuje zdarzenia.

Zadania uruchamiane przez cron nie powinny nakładać się bez kontroli. Blokada wykonania i idempotencja rozwiązują różne problemy: pierwsza ogranicza współbieżność, druga chroni przed wielokrotnym skutkiem tego samego zamiaru.

Co zapisać w logach i jak sprawdzić rozwiązanie

Loguj identyfikator operacji, numer próby, status, powód ponowienia i następny termin. Nie zapisuj tokena ani całego poufnego body. Przy wyczerpaniu prób skieruj zadanie do ręcznego sprawdzenia i wyślij pojedynczy alert administracyjny.

Przed wdrożeniem sprawdź co najmniej: utraconą odpowiedź po zatwierdzeniu zapisu, jednoczesne żądania z tym samym kluczem, zmianę danych przy zachowanym kluczu i restart procesu. Osobno ustal okres przechowywania rejestru. Usunięcie klucza zbyt wcześnie może zamienić stare ponowienie w nową operację.

Najczęstsze pytania

Czy każdy POST jest niebezpieczny do ponawiania?

Nie każdy, ale nie można zakładać jego idempotencji na podstawie samej metody. Sprawdź kontrakt endpointu. API może udostępniać bezpieczne ponowienia przez klucz operacji albo inną udokumentowaną regułę.

Gdzie generować klucz idempotencji?

Przed pierwszą próbą, przy tworzeniu trwałego zadania. Zapisz go razem z danymi operacji, aby przetrwał restart procesu. Nie generuj nowego klucza przy każdym wyjątku sieciowym.

Czy wystarczy sprawdzić, czy rekord istnieje?

Nie, jeśli pomiędzy sprawdzeniem a zapisem inny proces może zrobić to samo. Potrzebna jest ochrona na poziomie bazy: odpowiednia transakcja, unikalność i obsługa konfliktu.

Ile razy ponawiać zadanie?

Ustal limit prób oraz łączny budżet czasu według znaczenia operacji i polityki API. Po ich wyczerpaniu zachowaj stan do wyjaśnienia. Nieskończone retry ukrywa awarię i może zwiększać obciążenie.

Czy przykład SQLite zapewnia pojedyncze wysłanie e-maila?

Nie. Chroni tylko zapis zadania i rejestru w tej samej bazie. Zewnętrzna wysyłka wymaga odrębnej strategii dostarczenia i obsługi niepewnego wyniku.

Źródła

Data publikacji: 26.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *