Idempotence

Všechny endpointy AstroWay API jsou přirozeně idempotentní: stejný input vždy vrací stejný output, žádné vedlejší efekty (kromě strhávání kreditů a logování usage).

To znamená, že retry při síťových chybách je bezpečné. Ale aby opakovaný požadavek nestrhával kredity dvakrát, je třeba předat header Idempotency-Key.

Jak používat

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 - libovolný řetězec do 64 znaků, unikátní pro každou logickou operaci. Doporučeno - ULID nebo UUID v4.

Záruky

• Během 24 hodin po prvním požadavku s tímto klíčem opakované požadavky se stejným klíčem vrátí stejnou response bez opětovného výpočtu a bez strhávání kreditů.
• Pokud se body požadavku liší od originálu: vrátí se 409 Conflict s kódem idempotency_key_reuse.
• Po 24 hodinách je klíč zapomenut, nový požadavek se stejným klíčem bude běžným.

Poznámka

Idempotency je ochrana před dvojitým strháváním při síťových výpadcích, ne cache. Pro caching použij přirozený mechanismus X-Cache (5 minut, viz Kredity a limity).

Kdy to potřebuješ

• V webhook handlerech, kde přichází retry od externího systému (například platební poskytovatel nebo CRM posílá událost, kterou parsuješ a děláš výpočet)
• V background jobech, kde retry je standardní chování při chybách
• V CI/CD pipelinech, kde se test může spustit znovu

Pro běžné interakce “uživatel stiskl tlačítko → zobrazila se mapa” idempotency není potřeba - uživatel i tak uvidí výsledek, opakované klikání obvykle není.

Kdy ne používat

• Neumisťuj klíč, abys ušetřil kredity na stejných požadavcích: pro to je X-Cache (zdarma, 5 minut)
• Negenerej klíč z hash(body): pak ztratíš defaultní chování Idempotency-Key (opakovaný 409 při rozdílu v body)