Stanovte časový rozpočet celého procesu, nastavte timeout pre spojenie aj odpoveď, opakujte iba bezpečné dočasné chyby s exponenciálnym odstupom a rozptylom, rešpektujte limit poskytovateľa a idempotenciu a po vyčerpaní pokusov presuňte úlohu do viditeľného opravného stavu.
API integrácia musí počítať s pomalou odpoveďou, dočasnou nedostupnosťou aj limitom počtu volaní. Bez timeoutu môže jedno spojenie blokovať pracovníkov a zdroje. Bez kontrolovaného opakovania sa dočasná chyba zmení na stratené dáta. Príliš agresívne retry však zaťaží oslabenú službu a vytvorí lavínu, ktorá predĺži výpadok.
Odolnosť vzniká kombináciou rozumného časového rozpočtu, rozlíšenia chýb, idempotencie, rastúceho odstupu, náhodného rozptylu a frontu. Hodnoty sa nedajú univerzálne skopírovať. Musia vychádzať z používateľského procesu, kontraktu poskytovateľa, objemu a následkov oneskorenia. Každý mechanizmus potrebuje monitoring a hranicu, po ktorej zasiahne človek.
Odvoďte timeout od celého používateľského procesu
Najprv určte, ako dlho môže čakať používateľ alebo nadväzujúci systém. Tento rozpočet rozdeľte medzi DNS, spojenie, prenos, spracovanie a prípadné pokusy. Timeout klienta nemá byť dlhší než čas, po ktorom nadradená služba požiadavku aj tak zruší. Inak pokračuje zbytočná práca bez príjemcu výsledku.
Rozlišujte čas na nadviazanie spojenia a čas čítania odpovede. Dlhý export môže legitímne trvať dlhšie než jednoduché overenie. Ak operácia prekračuje interaktívny rozpočet, zmeňte ju na asynchrónnu úlohu so stavom. Nezvyšujte timeout bez diagnózy; môže iba skryť preťaženie alebo zablokovaný proces.
Klasifikujte chyby pred opakovaním
Dočasná sieťová chyba, preťaženie alebo niektoré serverové odpovede môžu byť vhodné na opakovanie. Neplatný vstup, chýbajúce oprávnenie alebo neexistujúci zdroj sa zvyčajne ďalším pokusom nezmenia. Konkrétne pravidlá určujte podľa kontraktu API a tela chyby, nie iba širokej skupiny stavových kódov.
Pri zápise overte idempotenciu ešte pred zapnutím retry. Timeout neznamená, že server operáciu nevykonal. Opakovaná platba alebo objednávka môže mať väčší dopad než pôvodný výpadok. Ak API neposkytuje bezpečný mechanizmus, použite stavové overenie alebo manuálnu kontrolu namiesto slepého opakovania.
- dočasná chyba s reálnou šancou na zotavenie
- idempotentná alebo bezpečne overiteľná operácia
- obmedzený počet pokusov a celkový vek
- viditeľný výsledok po definitívnom zlyhaní
Použite odstup, rozptyl a rešpektujte rate limit
Medzi pokusmi zväčšujte odstup a pridajte náhodný rozptyl, aby všetci klienti nezopakovali volanie v rovnakom okamihu. Nastavte hornú hranicu času aj počtu pokusov. Ak poskytovateľ vráti informáciu o ďalšom povolenom čase alebo zostávajúcej kapacite, spracujte ju podľa dokumentácie a zdieľajte rozpočet medzi pracovníkmi.
Rate limit sledujte na úrovni účtu, endpointu alebo používateľa podľa modelu služby. Paralelní pracovníci potrebujú koordináciu, inak každý verí, že má plnú kapacitu. Prioritizujte kritické operácie pred dávkovým importom. Cache alebo hromadný endpoint môžu znížiť počet volaní, ak zachovajú správnosť a aktuálnosť dát.
Oddeľte používateľskú požiadavku od frontu
Ak externé API nie je potrebné na okamžitú odpoveď, uložte zámer a spracujte ho vo fronte. Používateľ dostane potvrdenie prijatia, nie falošný prísľub dokončenia. Front umožní obmedziť súbeh, opakovať dočasné chyby a zachovať úlohu počas výpadku. Každá správa potrebuje stabilnú identitu a maximálny vek.
Po vyčerpaní pokusov presuňte úlohu do karantény s dôvodom a bezpečným spôsobom opravy. Nekonečné retry spotrebúva kapacitu a zakrýva trvalú chybu dát. Pri dlhšom výpadku môže ochranný mechanizmus dočasne zastaviť volania a pravidelne overovať zotavenie. Nesmie však zostať vypnutý bez alarmu.
Monitorujte technický aj obchodný výsledok
Sledujte latenciu, timeouty, počet pokusov, odpovede limitu, vek frontu a podiel úloh v karanténe. Rozdeľte metriky podľa poskytovateľa a operácie. Priemerný čas môže skryť dlhý chvost, ktorý ovplyvňuje zákazníkov. Upozornenie potrebuje vlastníka, prah a postup, nie iba surovú chybu.
Technická úspešnosť neznamená úplný proces. Porovnávajte počet prijatých objednávok, exportov alebo dokumentov s očakávaným tokom. Po zmene limitu či klienta urobte záťažový a regresný test v povolenom prostredí. Kapacitný plán aktualizujte pri raste objemu, nie až po prvom hromadnom zlyhaní.
- vek najstaršej čakajúcej operácie
- počet pokusov podľa typu chyby
- využitie limitu podľa klienta a endpointu
- obchodné objekty chýbajúce v cieľovom systéme
- čas zotavenia po uvoľnení externej kapacity
- vplyv dávkových úloh na kritické volania
Časté otázky
Koľkokrát sa má API požiadavka zopakovať?
Univerzálne číslo neexistuje. Závisí od časového rozpočtu, typu chyby, idempotencie, limitov a obchodného dopadu. Po hranici musí vzniknúť viditeľný opravný stav, nie tiché zahodenie.
Je dlhší timeout bezpečnejší?
Nie automaticky. Dlhý timeout viaže zdroje a môže prekročiť čas nadradeného procesu. Najprv diagnostikujte latenciu a pri dlhej práci použite asynchrónny model so stavom.
Čo robiť pri prekročení rate limitu?
Rešpektujte pokyny poskytovateľa, zastavte agresívne opakovanie, rozložte požiadavky a skontrolujte súbeh. Dlhodobo znížte zbytočné volania, použite dávky alebo dohodnite vhodnú kapacitu.
Zdroje a ďalšie čítanie
Web developer zo Spišskej Novej Vsi. Venuje sa WordPressu, WooCommerce, vlastným pluginom, API integráciám, webovým aplikáciám a praktickým AI automatizáciám.
