Idempotenza

La rete può cadere nel momento peggiore: invii una POST per un messaggio, la connessione si interrompe e non sai se l'email è partita. L'idempotenza ti permette di riprovare quella richiesta in sicurezza. Invia di nuovo lo stesso header Idempotency-Key e Bird restituisce la risposta originale invece di elaborare la richiesta una seconda volta.

Come funziona

L'idempotenza è opt-in. Aggiungi un header Idempotency-Key a una richiesta POST, PATCH, PUT o DELETE supportata. Le richieste senza questo header vengono elaborate normalmente, senza deduplicazione. Le richieste GET ignorano l'header.

Sulla API cliente, le mutazioni con ambito spazio di lavoro e organizzazione supportano il replay della risposta descritto di seguito. Le operazioni riservate all'utente, quelle senza ambito, le operazioni non autenticate e gli stream lo ignorano. Le operazioni con un contratto di replay separato definiscono il proprio comportamento nella relativa pagina di riferimento. Ad esempio, Crea una chiamata vocale conserva lo snapshot di accettazione originale per i tentativi corrispondenti quando fornisci una chiave.

Gli SDK generano una chiave per ogni chiamata mutante e la riutilizzano per i tentativi automatici, compresa la creazione di chiamate. Non è necessario fornirne una per i tentativi automatici SDK. Fornisci la tua chiave quando un'unica operazione prevista comprende chiamate SDK separate, ad esempio un nuovo tentativo dopo il riavvio dell'applicazione. Questi esempi mostrano quel caso.

await bird.email.send(
  {
    from: "hello@yourdomain.com",
    to: ["delivered@messagebird.dev"],
    subject: "Welcome!",
    html: "<p>Thanks for signing up.</p>",
  },
  { idempotencyKey: "welcome-user/usr_abc123" },
);

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Welcome!",
    html="<p>Thanks for signing up.</p>",
    options={"idempotency_key": "welcome-user/usr_abc123"},
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Welcome!",
	HTML:    "<p>Thanks for signing up.</p>",
}, option.WithIdempotencyKey("welcome-user/usr_abc123"))

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Welcome!',
    html: '<p>Thanks for signing up.</p>',
    options: new RequestOptions(idempotencyKey: 'welcome-user/usr_abc123'),
);

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user/usr_abc123" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Welcome!",
    "html": "<p>Thanks for signing up.</p>"
  }'

Una chiave è una qualsiasi stringa non vuota fino a 255 caratteri. Un valore di header vuoto salta la deduplicazione. Il formato consigliato è una chiave deterministica derivata dalle tue entità, <event-type>/<entity-id> (ad esempio welcome-user/usr_abc123), in modo che i tentativi tra riavvii del processo condividano la stessa chiave; anche un UUID casuale per operazione logica funziona. Gli SDK Bird generano automaticamente una chiave UUID per ogni richiesta mutante e la riutilizzano nei tentativi interni.

Le chiavi hanno come ambito il tuo spazio di lavoro, oppure la tua organizzazione sugli endpoint a livello di organizzazione. Una risposta completata viene conservata per 3 ore; un tentativo dopo quella finestra viene elaborato come una richiesta nuova. La finestra copre i tipici intervalli di ripetizione. Nessun record di deduplicazione rimane dopo la sua scadenza.

Replay

Quando Bird incontra una chiave che ha già completato, restituisce la risposta in cache, stesso codice di stato, stesso body, senza rieseguire la richiesta. Le risposte replicate includono un header aggiuntivo per distinguerle da un'elaborazione nuova:

Esempio di codice

HTTP/1.1 202 Accepted
Idempotency-Replay: true

Le risposte conservate possono includere rifiuti 4xx. Usa una nuova chiave quando correggi una richiesta: se il rifiuto è stato conservato, un nuovo tentativo identico lo riproduce, mentre una richiesta modificata restituisce 409 E01005 IdempotencyKeyReuse. Le risposte 5xx non vengono conservate, quindi riprova con la stessa chiave e la stessa richiesta.

Modalità di errore

Scenario	Risposta
Stessa chiave, stessa richiesta, originale completata	Risposta in cache replicata con Idempotency-Replay: true
Stessa chiave, corpo della richiesta o endpoint diverso	409, E01005 IdempotencyKeyReuse
Stessa chiave, richiesta originale ancora in corso	409, E01004 RequestInProgress
Chiave più lunga di 255 caratteri su un endpoint che dichiara l'header	422, E01001 ValidationError
Protezione di idempotenza non disponibile prima dell'esecuzione	503, E01033 IdempotencyUnavailable; questo tentativo non viene eseguito

Riutilizzare una chiave completata con una richiesta diversa è considerato un bug del client: Bird restituisce immediatamente 409 anziché consegnare silenziosamente una risposta che non corrisponde a ciò che hai inviato. Genera una nuova chiave per la nuova richiesta. Il confronto copre metodo, endpoint, parametri di percorso e query e il corpo grezzo della richiesta, inclusi gli spazi JSON. Per gli upload multipart vengono confrontati nomi delle parti, nomi dei file e contenuti; i boundary e l'ordine delle parti non influenzano il replay.

RequestInProgress indica che una richiesta concorrente con la stessa chiave non è ancora terminata, tipicamente un timeout lato client troppo aggressivo che riprova mentre il primo tentativo è ancora in elaborazione. Il lock in-flight scade entro 30 secondi, quindi attendi brevemente e riprova. Consulta Errori per la risposta di errore in cui questi vengono restituiti.

Cosa non viene messo in cache

Le risposte 5xx non vengono mai messe in cache. La chiave si sblocca e Bird può elaborare un nuovo tentativo come richiesta nuova. Riprova le risposte 5xx e i timeout con backoff esponenziale usando la stessa chiave e richiesta. Un'operazione può avere effetto prima che la sua risposta venga conservata; se quella risposta viene persa, o il lock in-flight scade, un nuovo tentativo può eseguire di nuovo l'operazione.

Se la protezione di idempotenza non è disponibile prima dell'esecuzione, la API restituisce 503 E01033 IdempotencyUnavailable senza eseguire questo tentativo. Mantieni la chiave su ogni tentativo. Questo errore non descrive l'esito di un tentativo precedente con la stessa chiave.

Indicazioni pratiche

Genera una chiave per operazione logica e riutilizzala per ogni tentativo HTTP di quell'operazione.
Riprova in caso di errori di rete, timeout e 5xx con backoff esponenziale, riutilizzando la stessa chiave ogni volta.
Tratta 409 IdempotencyKeyReuse come un bug nella generazione delle chiavi. Non riprovare.
Le chiavi sono opzionali per le mutazioni. Usane una quando hai bisogno di protezione per i tentativi; omettila nelle richieste GET.

Prossimi passi

Riferimento API per l'idempotenza: schemi di header e header di risposta
Concetti SDK: generazione automatica delle chiavi e comportamento dei tentativi negli SDK
Errori: la risposta di errore e il catalogo dei codici
Invio di email: endpoint di invio singolo e batch

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaOrder confirmation emails Esplora la funzionalitàOrder confirmation emails Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneVoice sequences