Idempotency

Wszystkie endpointy AstroWay API są naturalnie idempotentne: taki sam input zawsze daje taki sam output, żadnych efektów ubocznych (oprócz odejmowania kredytów i logowania usage).

To oznacza, że retry przy błędach sieciowych jest bezpieczny. Ale aby ponowne żądanie nie odejmowało kredytów dwukrotnie, trzeba przekazać nagłówek Idempotency-Key header.

Jak używać

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 - dowolny ciąg do 64 znaków, unikalny dla każdej logicznej operacji. Zalecane – ULID lub UUID v4.

Gwarancje

• Przez 24 godziny po pierwszym żądaniu z tym kluczem, ponowne żądania z tym samym kluczem zwracają taki sam response bez ponownego obliczenia i bez odejmowania kredytów.
• Jeśli body żądania różni się od oryginału: zwracany jest 409 Conflict z kodem idempotency_key_reuse.
• Po 24 godzinach klucz jest zapominany, nowe żądanie z tym samym kluczem będzie zwykłe.

Notatka

Idempotency - to ochrona przed podwójnym odejmowaniem przy błędach sieciowych, a nie cache. Do cachowania użyj naturalnego mechanizmu X-Cache (5 minut, zobacz Kredyty i limity).

Kiedy to potrzebne

• W webhook-handlerach, gdzie retry przychodzi od zewnętrznego systemu (np. payment-provider lub CRM wysyła zdarzenie, które parsujesz i wykonujesz obliczenia)
• W tle jobach, gdzie retry: standardowe zachowanie przy błędach
• W pipeline CI/CD, gdzie test może uruchomić się ponownie

Dla zwykłych interakcji “użytkownik kliknął przycisk → pokazano mapę” idempotentność nie jest potrzebna – użytkownik i tak zobaczy wynik, zwykle nie ma ponownych kliknięć.

Kiedy nie używać

• Nie ustawiaj klucza, aby zaoszczędzić kredyty przy identycznych żądaniach: do tego jest X-Cache (bezpłatny, 5 minut)
• Nie generuj klucza z hash(body): wtedy stracisz domyślne zachowanie Idempotency-Key (ponowny 409 przy rozbieżności body)