Chyby, idempotence a retry

Tato stránka popisuje integrační pravidla, která obvykle nejsou vidět ze samotného seznamu endpointů. Cílem je, aby klientský systém dokázal rozlišit validaci, autorizační problém, dočasnou chybu a doménový konflikt.

K čemu to použít

Integrace, která funguje, když jde všechno hladce, ještě není hotová. Hotová je, až přežije špatnou noc: výpadek sítě, chybná data u zdroje, přerušený běh. Pravidla na této stránce jsou k tomu, aby po takové noci nikdo neuklízel ručně.

• Noční synchronizace spadne v polovině. Import tří set lidí z HR systému přeruší síťová chyba po sto padesátém. Ráno ho spustíte znovu od začátku. Protože integrace používá stabilní externí identifikátory a rozlišuje create od update, prvních sto padesát lidí nevznikne podruhé. Bez toho byste dopoledne hledali a mazali duplicity.
• Jeden špatný záznam nezasype log. Zaměstnanec má v HR systému neplatný e-mail a server odpoví validační chybou. Integrace request neopakuje: data se sama neopraví. Záznam označí k opravě ve zdrojovém systému. Retry by jen tisíckrát zopakoval tutéž chybu.
• Výpadek přečkáte bez nočního telefonátu. Knowspread několik minut vrací dočasnou chybu. Integrace zkusí request krátce znovu, pak s exponenciálním backoffem, a po vyčerpání limitu pokusů uloží poslední odpověď a předá věc člověku. Ráno je v logu vidět, co se stalo a kde to skončilo.

Všechny tři situace stojí na jednom rozhodnutí: nejdřív poznat typ chyby, teprve pak zvolit reakci. Tabulka níže je k tomu vodítko.

Typy chyb

Situace	Typická reakce integrace
Neplatný token nebo credentials	Získat nový token, případně eskalovat špatné nastavení.
Neplatný payload	Opravit data ve zdrojovém systému a neposílat stejný request dokola.
Nenalezený objekt	Ověřit identifikátor a company space.
Doménový konflikt	Vyřešit stav v Knowspread nebo upravit pořadí synchronizace.
Dočasná chyba	Opakovat request s backoffem a limitem pokusů.

Idempotence

Integrace by měla být navržená tak, aby bezpečné opakování nezaložilo duplicitní uživatele, skupiny nebo členství. Prakticky to znamená:

• používat stabilní externí identifikátory,
• před hromadnou změnou znát aktuální stav,
• po dávce ověřit výsledek výpisem,
• rozlišovat create, update a restore scénáře.

Retry strategie

Opakování dává smysl u síťových chyb a dočasných serverových chyb. Nedává smysl u validačních chyb, kde se data sama nezmění.

Doporučený pattern:

1. krátký retry pro síťovou chybu,
2. exponenciální backoff,
3. limit pokusů,
4. uložení poslední odpovědi pro audit,
5. ruční zásah při opakovaném selhání.

Co ještě doplnit z kódu

• jednotný tvar error response,
• seznam status kódů podle endpointů,
• chování při částečně validních batch requestech,
• případná pravidla rate limitingu.