Hogyan tervezzünk API hibakezelést üzembiztosan

Egy webshop rendelése megérkezik, de a készletkezelő rendszer éppen nem válaszol. Az ügyfél visszaigazolást kap, a rendelés azonban nem jelenik meg a raktár feladatlistáján. Két órával később egy kolléga ezt egy táblázatból próbálja visszafejteni, majd kézzel rögzíti az adatokat. Ez nem egyszerű technikai hiba: készleteltéréshez, késedelmes kiszállításhoz, hibás számlázáshoz és bizalomvesztéshez vezethet. Ezért a kérdés nem csak az, hogyan tervezzünk API hibakezelést, hanem az is, hogy egy rendszerhiba esetén hogyan marad irányítható az üzleti folyamat.

Az API-k jellemzően rendszerek közötti kapcsolatot jelentenek. Webshopot kötnek össze ERP-vel, fuvarozói szolgáltatással, számlázóval, ügyfélkapcsolati rendszerrel vagy gyártási alkalmazással. Amíg minden válasz gyors és sikeres, ez a kapcsolat láthatatlan. Hiba esetén viszont kiderül, hogy az információ tényleg átkerült-e, ki felel a következő lépésért, és van-e mód biztonságosan folytatni a munkát.

A hibakezelés az üzleti következménynél kezdődik

Az első hiba sok szervezetnél az, hogy minden sikertelen API-hívást azonos kategóriaként kezel. Pedig lényeges különbség van aközött, hogy egy futárszolgálat öt másodpercig nem elérhető, egy partner rendszeréhez hibás azonosítóval kapcsolódunk, vagy egy rendelésben hiányzik a szállítási irányítószám.

A technikai üzenet önmagában ritkán segít az operációs csapatnak. A „400 Bad Request” nem mondja meg, hogy a rendelés javítható-e, újraküldhető-e, vagy az ügyféllel kell egyeztetni. A „500 Internal Server Error” pedig nem válaszolja meg, hogy a rendelés elveszett, feldolgozásra vár, vagy a célrendszerben már létrejött, csak a válasz veszett el.

Mielőtt fejlesztési szabályokat írunk, érdemes minden fontos integrációra végigvenni a folyamatot. Mi indítja el az adatátadást? Melyik rendszer az adat gazdája? Mi történik, ha az átadás sikertelen? Ki látja ezt, milyen határidővel, és hogyan ellenőrizhető a javítás? Egy rendelés, számla vagy gyártási utasítás nem válhat „bizonytalan állapotú” adattá csak azért, mert két rendszer között átmeneti kommunikációs zavar keletkezett.

Hogyan tervezzünk API hibakezelést folyamatonként?

A jó tervezés nem egyetlen általános hibalistával kezdődik, hanem azzal, hogy azonosítjuk a kritikus üzleti eseményeket. Egy webshopos rendelés átadása más védelmet igényel, mint egy termékkép szinkronizálása. Egy számla létrehozásánál vagy egy termelési készletfoglalásnál egyetlen duplikált kérés is pénzügyi vagy operatív problémát okozhat. Egy napi riport frissítése általában elvisel néhány perc késést, ha az adatpontosság megmarad.

Minden folyamatnál hasznos három kérdést feltenni:

1. Mi a hiba üzleti hatása, ha az adat nem jut át időben?
2. Megismételhető-e a művelet káros mellékhatás nélkül?
3. Mikor szükséges emberi döntés, és mikor javítható automatikusan a helyzet?

Ezekre adott válaszok alapján lehet arányos hibakezelést kialakítani. Nem minden hiba igényel azonnali riasztást. Ha egy nem kritikus adatfrissítés három perc késéssel érkezik meg, a folyamatos telefonos értesítés inkább zajt termel. Ha viszont egy sikertelen készletfoglalás miatt olyan terméket értékesít a webshop, amely már nincs raktáron, azonnali és egyértelmű kezelésre van szükség.

Legyenek egyértelmű hibatípusok

A hibákat célszerű nem pusztán HTTP-kódok, hanem kezelési mód szerint csoportosítani. Az átmeneti hibák közé tartozik például a hálózati megszakadás, a túlterhelt partneri rendszer vagy egy lejárt időkorlát. Ezeknél az ismételt próbálkozás általában indokolt. A tartós hibák, például a hibás jogosultság vagy megváltozott API-kapcsolat, nem oldódnak meg ismétléssel. Itt műszaki beavatkozás kell.

A harmadik csoport az üzleti adat- vagy szabályhiba. Ilyen lehet egy hiányzó adószám, egy nem létező cikkszám, egy lezárt rendelési állapot vagy egy nem engedélyezett kedvezmény. Ezeket a rendszereknek érthetően kell visszajelezniük a felelős munkatárs felé: mit kell javítani, hol, és mi történik a javítás után.

Ez a különbségtétel védi a csapatot attól, hogy ugyanazt a hibás rendelést százszor küldje újra, miközben egy másik, átmenetileg sikertelen adatátadás észrevétlenül elveszik a napi teendők között.

Az újrapróbálásnak legyen határa és szabálya

Egy API-kérés ismétlése kézenfekvő megoldásnak tűnik, de nem mindig biztonságos. Ha egy rendszer a számla létrehozását sikeresen végrehajtotta, majd a válaszadás előtt megszakadt a kapcsolat, az újraküldött kérés második számlát hozhat létre. Ugyanez előfordulhat rendelésrögzítésnél, fizetési kérésnél vagy fuvarcímke-generálásnál is.

Ezért a kritikus műveletekhez egyedi azonosító szükséges. A fogadó rendszernek fel kell ismernie, hogy ugyanarról az üzleti eseményről érkezik ismételt kérés, és nem szabad még egyszer végrehajtania azt. Ezt nevezzük idempotens működésnek. A vezetői szempont egyszerű: egy átmeneti hiba ne eredményezzen kétszeres pénzügyi, raktári vagy ügyfélkommunikációs műveletet.

Az újrapróbálás időzítését is szabályozni kell. A néhány másodperces, majd fokozatosan hosszabb várakozás sok esetben megfelelő. A folyamatos, azonnali ismétlés viszont tovább terhelheti a hibás rendszert, és elfedheti a valódi problémát. Meghatározott számú próbálkozás után az eset kerüljön ellenőrizhető várólistára, ne tűnjön el a naplófájlokban.

Ne a kolléga legyen a rendszerek közötti hibaelhárító

Sok cégben az integráció hibakezelése valójában egy tapasztalt munkatárs fejében létezik. Ő tudja, melyik e-mailt kell keresni, melyik rendszerben kell újraindítani a műveletet, és melyik adatot kell kézzel módosítani. Ez gyors megoldásnak látszik, de személyfüggő folyamatot épít. Szabadság, betegség vagy növekedés esetén ez azonnal kockázattá válik.

A kezelhető rendszer nem hagyja magára a felhasználót egy technikai hibaüzenettel. A felelős szerepkör számára olyan munkalista kell, amelyben látszik az érintett üzleti objektum - például rendelésazonosító, partner vagy számla -, a hiba oka, az eddigi próbálkozások és a következő ajánlott lépés. A hiba kijavítása után a folyamatnak szabályosan folytathatónak kell lennie, lehetőleg kézi adatmásolás nélkül.

Ez nem jelenti azt, hogy minden kivételt automatizálni kell. Egy kiemelt ügyfél rendelésének szállítási feltétele vagy egy szokatlan gyártási tétel valódi emberi mérlegelést igényelhet. A cél az, hogy a kolléga döntést hozzon, ne rendszerek között adatokat vadásszon és ugyanazt az információt több helyre gépelje be.

Naplózás és megfigyelhetőség: bizonyíték kell, nem feltételezés

Amikor egy vezető azt kérdezi, „átment ez a rendelés?”, a rendszernek egyértelmű választ kell adnia. Ehhez minden fontos API-műveletnél szükség van nyomon követhető azonosítóra, időbélyegre, kérési eredményre, feldolgozási állapotra és - ahol indokolt - a hiba részletes okára. A személyes, fizetési vagy egyéb érzékeny adatokat természetesen nem szabad ellenőrizetlenül naplózni.

A napló azonban önmagában nem üzemeltetési modell. Figyelni kell a sikertelen hívások arányát, a feldolgozási sorok hosszát, a válaszidők romlását és az ismétlődő üzleti adatproblémákat. Ha ugyanaz a partnercikkszám hetente hibát okoz, ott nem egyszeri incidensről, hanem adatgazdai vagy folyamatproblémáról van szó.

Érdemes azt is mérni, mennyi idő telik el a hiba keletkezése és rendezése között, hány üzleti esemény vár feldolgozásra, valamint hányszor kell emberi beavatkozás. Ezek a mutatók nem csak az IT teljesítményét írják le. Megmutatják, mennyire kiszámítható a rendelésfeldolgozás, a raktári működés vagy a pénzügyi adminisztráció.

A partneri kapcsolatok hibáira is fel kell készülni

Nem minden API saját rendszerhez kapcsolódik. Fuvarozók, fizetési szolgáltatók, beszállítói platformok és ügyfélrendszerek is lehetnek a folyamat részei. Ilyenkor az elérhetőség, a válaszidő, a verzióváltás és az adatminőség részben külső szereplőtől függ.

A jó architektúra ezért nem épít korlátlan bizalomra. Meghatározza az időkorlátokat, korlátozza a hibás partner felé indított ismételt kéréseket, és ahol az üzleti folyamat ezt megengedi, leválasztja az azonnali ügyfélélményt a háttérfeldolgozásról. Egy rendelés például rögzíthető belsőleg akkor is, ha a fuvarcímke csak később készül el. De ezt csak akkor szabad megtenni, ha világos, ki és mikor ellenőrzi a későbbi teljesülést.

A változáskezelés is ide tartozik. Egy külső API mezőinek vagy szabályainak módosítása előbb-utóbb bekövetkezik. Verziózott kapcsolatokkal, tesztkörnyezettel és ellenőrzött bevezetéssel a változás tervezhető feladat marad, nem hétfő reggeli üzemzavar.

A jó API hibakezelés végső soron nem azt ígéri, hogy hiba sosem történik. Azt biztosítja, hogy hiba esetén az üzleti folyamat állapota ismert marad, a következő lépés egyértelmű legyen, és a szervezet ne egyetlen ember rutinjára vagy kézi táblázatokra támaszkodjon. Innen érdemes tovább gondolkodni: melyik jelenlegi rendszerkapcsolatuknál nem tudnák ma bizonyítani, mi történt egy sikertelen adatátadás után?