Idempotency

Toate endpoint-urile AstroWay API sunt idempotente prin natura lor: același input dă mereu același output, fără efecte secundare (cu excepția debitării creditelor și a jurnalizării usage).

Asta înseamnă că un retry după erori de rețea este sigur. Dar ca o cerere repetată să nu debiteze creditele de două ori, trebuie să trimiți header-ul Idempotency-Key.

Cum se folosește

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 este un șir arbitrar de până la 64 de caractere, unic pentru fiecare operație logică. Recomandat: ULID sau UUID v4.

Garanții

• Timp de 24 de ore după prima cerere cu această cheie, cererile repetate cu aceeași cheie returnează același response, fără recalculare și fără debitarea creditelor.
• Dacă body-ul cererii diferă de original, se returnează 409 Conflict cu codul idempotency_key_reuse.
• După 24 de ore cheia este uitată, iar o nouă cerere cu aceeași cheie va fi una obișnuită.

Mențiune

Idempotency este o protecție împotriva debitării duble la căderile de rețea, nu un cache. Pentru cache folosește mecanismul natural X-Cache (5 minute, vezi Credite și limite).

Când este necesar

• În webhook handlers, unde retry-ul vine de la un sistem extern (de exemplu, un procesator de plăți sau un CRM trimite un eveniment pe care îl parsezi și pe baza căruia faci un calcul)
• În job-uri de fundal, unde retry-ul este comportamentul standard la erori
• În pipeline-uri CI/CD, unde un test poate rula din nou

Pentru interacțiuni obișnuite de tipul “utilizatorul a apăsat butonul → am afișat harta”, idempotența nu este necesară: utilizatorul vede oricum rezultatul, iar clicurile repetate de obicei lipsesc.

Când să nu o folosești

• Nu seta cheia ca să economisești credite la cereri identice: pentru asta există X-Cache (gratuit, 5 minute)
• Nu genera cheia din hash(body): astfel pierzi comportamentul implicit al Idempotency-Key (409 la repetare când body-ul diferă)