Idempotenza

Usa Idempotency-Key quando una connessione interrotta ti lascia senza sapere se la richiesta è andata a buon fine. La garanzia è l'accettazione esattamente una volta: i nuovi tentativi con la stessa chiave e una richiesta identica devono risolversi in un'unica operazione accettata entro la finestra di conservazione di 3 ore, anche se hai perso la risposta originale.

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 nuovi tentativi corrispondenti quando fornisci una chiave.

Gli SDK generano una chiave per ogni chiamata mutante e la riutilizzano per i nuovi tentativi automatici, compresa la creazione di chiamate. Non è necessario fornirne una per i nuovi 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 nuovi 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 loro nuovi 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 nuovo tentativo dopo quella finestra può essere elaborato come una richiesta nuova. Se dopo la scadenza l'esito dell'operazione originale è sconosciuto, lascia l'operazione in sospeso e verificane lo stato prima di inviarla di nuovo.

Replay

Un nuovo tentativo corrispondente entro tre ore deve risolversi nell'operazione originale. Quando la sua risposta è conservata, API restituisce lo stesso codice di stato e lo stesso body senza accettare un'altra operazione. Le risposte riprodotte includono un header aggiuntivo per distinguerle da un'elaborazione nuova:

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 come risposte completate. La garanzia di accettazione esattamente una volta copre anche i nuovi tentativi dopo questi errori.

Modalità di errore

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. Di solito si tratta di un timeout lato client troppo aggressivo che riprova mentre il primo tentativo è ancora in elaborazione. Attendi brevemente e riprova con la stessa chiave e la stessa richiesta. Consulta Errori per la risposta di errore in cui questi vengono restituiti.

Cosa non viene messo in cache

Le risposte 5xx non vengono conservate come risposte completate. Riprova entro tre ore con un backoff limitato, la stessa chiave e una richiesta identica. La garanzia di accettazione esattamente una volta vale anche quando la risposta originale è andata persa.

Se la protezione di idempotenza non è disponibile prima dell'esecuzione, la API restituisce 503 E01033 IdempotencyUnavailable senza eseguire questo tentativo. Mantieni la stessa chiave ogni volta che riprovi. 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.
• In caso di errori di rete, timeout e 5xx, riprova entro tre ore con un backoff esponenziale limitato, mantenendo la chiave e una richiesta identica.
• Se i tentativi si esauriscono o la conservazione scade, lascia irrisolto l'esito sconosciuto. Verifica l'esito prima di inviare un'altra operazione, sia con la vecchia chiave sia con una nuova.
• Per gli invii di messaggi, controlla lo stato del messaggio per confermare la consegna dopo l'accettazione.
• Tratta 409 IdempotencyKeyReuse come un bug nella generazione delle chiavi. Non riprovare.
• Le chiavi sono opzionali per le mutazioni. Usane una quando devi riprovare in sicurezza; 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 nuovi tentativi negli SDK
• Errori: la risposta di errore e il catalogo dei codici
• Invio di email: endpoint di invio singolo e batch