Idempotency

Minden AstroWay API endpoint természetesen idempotens: ugyanaz az input mindig ugyanazt az outputot adja, nincsenek mellékhatások (kivéve a kredit levonását és a használat naplózását).

Ez azt jelenti, hogy a hálózati hibák esetén történő újrapróbálás biztonságos. De hogy a második kérés ne vonjon le kétszer kreditet, át kell adni az Idempotency-Key headert.

Hogyan használd

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - tetszőleges karakterlánc maximum 64 karakter hosszúságban, egyedi minden logikai művelethez. Ajánlott - ULID vagy UUID v4.

Garanciák

• Az első kérés után 24 órán belül ugyanazzal a kulccal küldött ismételt kérések ugyanazt a választ adják vissza, újraszámítás nélkül és kredit levonása nélkül.
• Ha a kérés body-ja eltér az eredetitől: 409 Conflict hibaüzenetet ad vissza idempotency_key_reuse kóddal.
• 24 óra után a kulcsot elfelejtjük, egy új kérés ugyanazzal a kulccsal normál kérés lesz.

Megjegyzés

Az idempotencia védelmet nyújt a kétszeres levonás ellen hálózati hibák esetén, nem pedig gyorsítótárazásra szolgál. A gyorsítótárazáshoz használd a beépített X-Cache mechanizmust (5 perc, lásd Kreditek és limit).

Mikor szükséges

• Webhook handler-ekben, ahol az újrapróbálkozás külső rendszertől érkezik (például fizetési szolgáltató vagy CRM eseményt küld, amit feldolgozol és számítást végezsz)
• Háttér feladatokban (job), ahol az újrapróbálkozás a hibák esetén sztenderd viselkedés
• CI/CD pipeline-okban, ahol a teszt ismételten futtatható

A normál felhasználói interakciókhoz (“felhasználó megnyom egy gombot → megjelenik a horoszkóp”) az idempotencia nem szükséges - a felhasználó így is látni fogja az eredményt, és általában nincsenek ismételt kattintások.

Mikor ne használd

• Ne állj be kulcsot, hogy megtakarítsd a krediteket az azonos kéréseknél: erre van az X-Cache (ingyenes, 5 perc)
• Ne generálj kulcsot hash(body)-ból: ekkor elveszíted az Idempotency-Key alapértelmezett viselkedését (ismételt 409 hiba body eltérés esetén)