Idempotenza

Le reti falliscono. Se un POST va in timeout, non sai se è stato applicato, e riprovare alla cieca potrebbe creare un prodotto duplicato. L'header Idempotency-Key risolve il problema:

curl -X POST https://api.nembol.com/rest/v1/products \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: 7d5c1f6e-2f5b-4a1e-9c3d-0a8b7c6d5e4f" \
  -d '{ "title": "…" }'

• Genera una chiave univoca per ogni operazione logica (un UUID è perfetto), e riusa la stessa chiave quando riprovi quell'operazione.
• Ripetendo la stessa chiave con lo stesso payload ricevi la risposta originale salvata (stesso codice di stato e stesso body, più l'header Idempotent-Replayed: true). Nulla viene rieseguito. Anche gli errori vengono salvati: un 4xx (es. un 422) viene restituito così com'era, anche se la causa è stata nel frattempo corretta da parte tua o nostra, quindi invia una nuova chiave dopo aver modificato la richiesta o dopo una correzione. Un 5xx non viene mai salvato: riprovando con la stessa chiave la richiesta viene eseguita di nuovo.
• Ripetendo la stessa chiave con un payload diverso ricevi un errore 409 (idempotency_key_reused). Le chiavi non vengono mai riusate in silenzio.
• Le chiavi vengono ricordate per 24 ore; lunghezza massima 255 caratteri.

Supportata (e consigliata) su ogni endpoint POST, PATCH e DELETE.

Ricetta per i retry: in caso di timeout o 5xx, riprova con la stessa chiave e backoff esponenziale (es. 1s, 2s, 4s, …); in caso di 429, attendi Retry-After poi riprova con la stessa chiave.

Ultimo aggiornamento il 20 ottobre 2026