Come evito di inviare lo stesso SMS due volte?

La connessione può cadere dopo che Bird accetta un SMS ma prima che la tua applicazione riceva la risposta. Riprovare con una chiave nuova può creare un secondo invio, perché Bird lo tratta come una richiesta separata.

Come funziona la chiave?

Imposta un header Idempotency-Key per ogni invio SMS intenzionale e riutilizzalo quando riprovi la stessa richiesta identica. La garanzia di accettazione esattamente una volta significa che i nuovi tentativi corrispondenti entro tre ore devono risolversi nello stesso invio accettato, anche se ne hai perso la risposta.

Ad esempio, una conferma d'ordine mantiene la stessa chiave dopo un timeout, quando riprovi la richiesta. Una conferma per un ordine diverso riceve una chiave diversa.

Le risposte riprodotte includono Idempotency-Replay: true, che permette ai tuoi log di distinguere un replay da una richiesta elaborata per la prima volta.

Le chiavi SMS sono limitate al tuo spazio di lavoro. Bird conserva le risposte completate per tre ore in base al suo contratto di idempotenza. Oltre quella finestra, la stessa chiave può eseguire una nuova richiesta perché il record di replay è scaduto. Un tentativo un giorno dopo richiede quindi la riconciliazione dell'esito originale prima di un altro invio.

Cosa mi dicono le risposte di errore?

Il codice di errore distingue una richiesta modificata, una richiesta non completata e una protezione non disponibile.

• 409 con E01005 IdempotencyKeyReuse: la stessa chiave è stata usata per una richiesta diversa. Correggi l'assegnazione della chiave prima di riprovare, perché questa chiave appartiene alla richiesta originale. Bird confronta il metodo, l'endpoint, il path e i parametri di query, e il body grezzo. Anche una modifica JSON di spazi rende la richiesta diversa.
• 409 con E01004 RequestInProgress: una richiesta concorrente con la stessa chiave non è ancora terminata. Attendi brevemente e riprova con la stessa chiave e richiesta, così l'originale può completarsi.
• 503 con E01033 IdempotencyUnavailable: la protezione non era disponibile prima dell'esecuzione, quindi questo tentativo non è stato eseguito. Riprova con backoff usando la stessa chiave e richiesta. Questa risposta non stabilisce l'esito di un tentativo precedente.
• Altre risposte 5xx o timeout: riprova con backoff usando la stessa chiave e richiesta. La garanzia di accettazione esattamente una volta copre questi nuovi tentativi entro tre ore. Fermati quando hai esaurito il numero di nuovi tentativi previsto.

L'header di idempotenza preserva l'identità della richiesta attraverso questi tentativi.

La chiave garantisce zero duplicati?

La garanzia è l'accettazione esattamente una volta per richieste identiche con la stessa chiave, nello stesso spazio di lavoro ed entro tre ore. Questi nuovi tentativi devono risolversi in un solo invio accettato, anche dopo una risposta persa. Controlla lo stato del messaggio per confermare la consegna.

Dopo la finestra di conservazione di tre ore, la chiave originale può identificare una nuova operazione. Se non conosci l'esito originale, riconcilialo prima di inviare di nuovo.

Conserva i record di eventi e invii della tua applicazione, così puoi riconciliare un esito incerto prima di inviare di nuovo. Includi il numero d'ordine o di riferimento nel messaggio, così il destinatario può riconoscere a quale evento si riferisce.

E un messaggio che il telefono mostra due volte?

Una chiave di idempotenza governa i tentativi API; non controlla come il telefono del destinatario visualizza un messaggio. Uno screenshot da solo non stabilisce dove il duplicato ha avuto origine.

Confronta il log di invio completo della tua applicazione con i record dei messaggi di Bird. Più message ID accettati possono confermare più invii. Trovare un solo ID in un log incompleto non dimostra che il duplicato è avvenuto a valle. Includi gli ID pertinenti, la destinazione e i timestamp quando chiedi al supporto di indagare.

Cosa devo fare?

1. Assegna una chiave a ogni invio SMS intenzionale e riutilizza la richiesta identica per i suoi tentativi.
2. Riprova errori di rete, timeout e risposte 5xx con backoff, mantenendo la stessa chiave e la richiesta identica entro tre ore.
3. Correggi i conflitti di richieste modificate e ritarda i tentativi quando la richiesta originale è ancora in corso.
4. Lascia irrisolti i nuovi tentativi esauriti o scaduti finché non ne riconcili l'esito, prima di decidere se un altro invio è appropriato.