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?

Imposti un header Idempotency-Key per ogni invio SMS intenzionale e lo riutilizzi quando riprovi la stessa richiesta identica. Quando Bird conserva la risposta originale, un tentativo corrispondente restituisce quella risposta senza eseguire di nuovo l'invio.

Ad esempio, una conferma d'ordine mantiene la stessa chiave attraverso un timeout e il suo tentativo successivo. 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. Il lock in-flight scade entro 30 secondi. La scadenza non stabilisce se l'invio originale ha avuto effetto.
• 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. Bird non conserva le risposte 5xx. Un tentativo riproduce una risposta positiva conservata oppure può eseguire di nuovo se nessuna risposta è stata conservata.

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

La chiave garantisce zero duplicati?

La chiave riduce gli invii duplicati, ma non garantisce un'unica esecuzione.

Un invio può avere effetto prima che Bird conservi la sua risposta. Se la conservazione della risposta fallisce o il lock in-flight scade, un tentativo può eseguire di nuovo l'invio. La finestra di conservazione di tre ore limita anch'essa la protezione di replay.

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, conservando la chiave per mantenere ogni protezione di replay disponibile.
3. Correggi i conflitti di richieste modificate e ritarda i tentativi quando la richiesta originale è ancora in corso.
4. Riconcilia gli invii incerti, inclusi quelli oltre la finestra di replay di tre ore, prima di decidere se un altro invio è appropriato.