Richieste idempotenti

Una richiesta può non riuscire dopo che Sursa ha già fatto il lavoro: la connessione cade, oppure il tuo processo si riavvia prima che arrivi la risposta. Se invii di nuovo lo stesso POST, potresti creare una seconda scheda o un secondo webhook. Una chiave di idempotenza lo impedisce.

Invia un’intestazione Idempotency-Key con ogni POST e PATCH. Se Sursa ha già visto una richiesta con questa chiave, non esegue di nuovo l’operazione: restituisce la risposta che ha salvato la prima volta.

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."}'

Una richiesta ripetuta riceve lo stesso stato e lo stesso corpo della prima, con un’intestazione in più:

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

La richiesta ripetuta ha il proprio X-Request-Id.

Scegliere una chiave

Usa un nuovo valore casuale, come un UUID v4, per ogni operazione logica: “crea questa scheda”, “registra questo webhook”. Usa lo stesso valore per ogni nuovo tentativo di quell’operazione, e mai per un’operazione diversa.
Una buona chiave si ricava dai tuoi dati, quando ne hai, per esempio sync-2026-10-24-record-1042. Così anche un job riavviato che ha perso la memoria invia di nuovo la stessa chiave.
La chiave è composta da 1 a 255 caratteri ASCII stampabili. Qualsiasi altro valore restituisce 400 con il codice api.idempotency_key_invalid.

Cosa fa Sursa con la chiave

Situazione	Risposta
Prima richiesta con questa chiave	L’operazione viene eseguita normalmente.
Stessa chiave, stessa richiesta, la prima si è conclusa con `2xx` o `4xx`	La risposta salvata, con `Idempotency-Replayed: true`. L’operazione non viene eseguita di nuovo.
Stessa chiave, la prima richiesta è ancora in corso	`409` `api.idempotency_in_progress` con `Retry-After: 1`. Attendi e riprova.
Stessa chiave, ma metodo, percorso, `Content-Type` o corpo diversi	`409` `api.idempotency_mismatch`. La chiave è già usata da un’altra richiesta.
La prima richiesta si è conclusa con `5xx` o `429`	La chiave viene liberata: la richiesta successiva con essa esegue di nuovo l’operazione.

Una chiave è valida per 24 ore. Dopo, la stessa chiave avvia una nuova operazione.
Le chiavi sono separate per organizzazione e per chi effettua la chiamata: due chiavi API diverse possono usare lo stesso valore senza influenzarsi.
Anche una risposta di errore 4xx viene salvata. Una richiesta che non ha superato la validazione non riesce allo stesso modo quando viene ripetuta con la stessa chiave; correggila e inviala con una nuova chiave.

Quali richieste ne hanno bisogno

Metodo	Idempotency-Key
`POST`, `PATCH`	Inviala. Ogni endpoint che salva la sua risposta per una ripetizione elenca l’intestazione nel riferimento API.
`GET`, `PUT`, `DELETE`	Non serve: per loro natura questi metodi si possono ripetere in sicurezza. L’intestazione viene accettata e non ha effetto.
`POST` che legge soltanto, come la ricerca, i report finanziari e `POST /v1/catalog/resolve`	Accettata, ma non viene salvato nulla: la richiesta viene semplicemente eseguita di nuovo.

Alcune operazioni si possono ripetere in sicurezza anche senza l’intestazione:

PUT /v1/cards-by-external-id/{external_id} crea o sostituisce la scheda con il tuo ID; una ripetizione con lo stesso contenuto non cambia nulla.
I documenti di una fonte personalizzata sono identificati dal tuo external_id; inviare di nuovo lo stesso documento restituisce unchanged.
Una risposta in streaming di POST /v1/chat usa il campo request_id del corpo invece dell’intestazione. Vedi Creare un bot di domande e risposte.

Ritentare in sicurezza

Combina la chiave con le regole per i nuovi tentativi di Errori: crea la chiave una sola volta, prima del primo tentativo, e inviala con ogni tentativo della stessa operazione.