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