Cereri idempotente

O cerere poate eșua după ce Sursa a făcut deja lucrul cerut: conexiunea se întrerupe sau procesul dumneavoastră repornește înainte să sosească răspunsul. Dacă trimiteți din nou același POST, ați putea crea o a doua fișă sau un al doilea webhook. O cheie de idempotență previne acest lucru.

Trimiteți un antet Idempotency-Key cu fiecare POST și PATCH. Dacă Sursa a văzut deja o cerere cu această cheie, nu execută operația din nou: returnează răspunsul salvat prima dată.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

O cerere repetată primește același status și același corp ca prima, cu un antet în plus:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

Cererea repetată are propriul X-Request-Id.

Alegerea cheii

Folosiți o valoare aleatoare nouă, de exemplu un UUID v4, pentru fiecare operație logică: „creează această fișă”, „înregistrează acest webhook”. Folosiți aceeași valoare pentru fiecare reîncercare a operației respective și niciodată pentru alta.
O cheie bună este derivată din propriile date, atunci când există, de exemplu sync-2026-10-24-record-1042. Astfel, chiar și un job repornit, care și-a pierdut memoria, trimite din nou aceeași cheie.
Cheia are între 1 și 255 de caractere ASCII imprimabile. Orice altceva returnează 400 cu codul api.idempotency_key_invalid.

Ce face Sursa cu cheia

Situație	Răspuns
Prima cerere cu această cheie	Operația se execută ca de obicei.
Aceeași cheie, aceeași cerere, prima s-a încheiat cu `2xx` sau `4xx`	Răspunsul salvat, cu `Idempotency-Replayed: true`. Operația nu se execută din nou.
Aceeași cheie, prima cerere este încă în execuție	`409` `api.idempotency_in_progress` cu `Retry-After: 1`. Așteptați și reîncercați.
Aceeași cheie, altă metodă, altă cale, alt `Content-Type` sau alt corp	`409` `api.idempotency_mismatch`. Cheia este deja ocupată de o altă cerere.
Prima cerere s-a încheiat cu `5xx` sau `429`	Cheia este eliberată: următoarea cerere cu ea execută din nou operația.

O cheie este valabilă 24 de ore. După aceea, aceeași cheie pornește o operație nouă.
Cheile sunt separate pentru fiecare organizație și pentru fiecare apelant: două chei API diferite pot folosi aceeași valoare fără să se influențeze reciproc.
Și un răspuns de eroare 4xx este salvat. O cerere care nu a trecut validarea eșuează la fel când este repetată cu aceeași cheie; corectați-o și trimiteți-o cu o cheie nouă.

Ce cereri au nevoie de ea

Metodă	Idempotency-Key
`POST`, `PATCH`	Trimiteți-l. Fiecare endpoint care își salvează răspunsul pentru o repetare menționează antetul în referința API.
`GET`, `PUT`, `DELETE`	Nu este necesar: prin sensul lor, aceste metode pot fi repetate în siguranță. Antetul este acceptat și nu are niciun efect.
`POST` care doar citește, de exemplu căutarea, rapoartele financiare și `POST /v1/catalog/resolve`	Este acceptat, dar nu se salvează nimic: cererea se execută pur și simplu din nou.

Unele operații pot fi repetate în siguranță chiar și fără antet:

PUT /v1/cards-by-external-id/{external_id} creează sau înlocuiește fișa cu identificatorul dumneavoastră; o repetare cu același conținut nu schimbă nimic.
Documentele unei surse personalizate sunt identificate prin external_id; trimiterea din nou a aceluiași document returnează unchanged.
Un răspuns transmis în flux de POST /v1/chat folosește câmpul request_id din corp în locul antetului. Vedeți Construiți un bot de întrebări și răspunsuri.

Reîncercări sigure

Combinați cheia cu regulile de reîncercare din Erori: creați cheia o singură dată, înainte de prima încercare, și trimiteți-o la fiecare încercare a aceleiași operații.