Vai al contenuto
TapLogic API
English

Idempotenza

Una rete che cade a metà richiesta non deve creare due endpoint o due inviti. Con Idempotency-Key ripeti la stessa scrittura senza effetti doppi.

curl -X POST "https://api.taplogic.it/v1/members" \
  -H "Authorization: Bearer $TAPLOGIC_API_KEY" \
  -H "Idempotency-Key: 2f1c6a8e-7b0d-4b8e-9f51-3a2c9d4e7f10" \
  -H "Content-Type: application/json" \
  -d '{"email":"giulia.rossi@esempio.it","role":"member"}'

Come funziona

  1. Aggiungi Idempotency-Key a ogni POST, PATCH e DELETE: un valore unico per operazione, per esempio un UUID v4 (massimo 255 caratteri).
  2. La prima richiesta viene eseguita e la sua risposta viene salvata per 24 ore, legata alla chiave API.
  3. Una ripetizione con la stessa chiave e lo stesso corpo restituisce la stessa risposta, con l'intestazione Idempotent-Replayed: true. Nessun effetto nuovo.
  4. Anche gli errori 4xx vengono salvati e ripetuti: correggi la richiesta e usa una chiave nuova.
  5. Gli errori 5xx non vengono salvati: ripeti con la stessa chiave.

Conflitti

  • 422 idempotency_key_mismatch: stessa chiave, corpo o percorso diversi. È quasi sempre un errore nel codice.
  • 409 idempotency_in_progress: la prima richiesta è ancora in corso. Attendi un momento e ripeti.
  • 409 idempotency_replay_unavailable: la risposta salvata non è più leggibile. Controlla lo stato della risorsa e usa una chiave nuova.

Dopo 24 ore la chiave scade e una richiesta con lo stesso valore viene eseguita di nuovo.