Idempotency

Tutti gli endpoint di AstroWay API sono idempotenti per natura: lo stesso input produce sempre lo stesso output, senza effetti collaterali (a parte l’addebito dei crediti e il logging dell’utilizzo).

Questo significa che il retry in caso di errori di rete è sicuro. Ma perché una richiesta ripetuta non addebiti i crediti due volte, devi passare l’header Idempotency-Key.

Come usarlo

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 è una stringa arbitraria lunga fino a 64 caratteri, univoca per ogni operazione logica. Consigliato: ULID o UUID v4.

Garanzie

Per 24 ore dalla prima richiesta con questa chiave, le richieste ripetute con la stessa chiave restituiscono la stessa response, senza ricalcolo e senza addebito di crediti.
Se il body della richiesta differisce dall’originale, viene restituito 409 Conflict con il codice idempotency_key_reuse.
Dopo 24 ore la chiave viene dimenticata e una nuova richiesta con la stessa chiave viene trattata come una richiesta normale.

Quando serve

Negli handler dei webhook, dove il retry arriva da un sistema esterno (per esempio un provider di pagamenti o un CRM invia un evento che tu analizzi per poi eseguire un calcolo)
Nei job in background, dove il retry è il comportamento standard in caso di errore
Nelle pipeline CI/CD, dove un test può essere rieseguito

Per le interazioni normali del tipo “l’utente ha premuto un pulsante → abbiamo mostrato il tema” l’idempotenza non serve: l’utente vedrà comunque il risultato e di solito non ci sono clic ripetuti.

Quando non usarla

Non impostare la chiave per risparmiare crediti su richieste identiche: per questo c’è X-Cache (gratuito, 5 minuti)
Non generare la chiave da hash(body): perderesti il comportamento predefinito di Idempotency-Key (il 409 in caso di body diverso)

Utile?

Suggerisci modifica

Ultimo aggiornamento: 25 set 2026