Idempotence

Utilisez Idempotency-Key lorsqu'une connexion interrompue vous empêche de savoir si votre requête a abouti. La garantie est une acceptation unique : les nouvelles tentatives avec la même clé et une requête identique doivent aboutir à une seule opération acceptée pendant la fenêtre de conservation de 3 heures, même si vous avez perdu la réponse d'origine.

Fonctionnement

L'idempotence est optionnelle. Ajoutez un en-tête Idempotency-Key à une requête POST, PATCH, PUT ou DELETE prise en charge. Les requêtes sans cet en-tête sont traitées normalement, sans déduplication. Les requêtes GET ignorent l'en-tête.

Sur l'API client, les mutations limitées à l'espace de travail ou à l'organisation prennent en charge le rejeu de réponse décrit ci-dessous. Les opérations réservées à l'utilisateur, les opérations non authentifiées sans portée et les flux le contournent. Les opérations dotées d'un contrat de rejeu distinct définissent leur comportement dans leur page de référence. Par exemple, Créer un appel vocal conserve l'instantané d'acceptation d'origine pour les nouvelles tentatives correspondantes lorsque vous fournissez une clé.

Les SDK génèrent une clé pour chaque appel mutatif et la réutilisent pour les nouvelles tentatives automatiques, y compris lors de la création d'appel. Vous n'avez pas besoin d'en fournir une pour les nouvelles tentatives automatiques de SDK. Fournissez la vôtre lorsqu'une même opération couvre plusieurs appels SDK distincts, par exemple une nouvelle tentative après le redémarrage de votre application. Ces exemples illustrent ce cas.

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>"
  }'

Une clé est une chaîne non vide de 255 caractères maximum. Une valeur d'en-tête vide désactive la déduplication. Le format recommandé est une clé déterministe dérivée de vos propres entités, <event-type>/<entity-id> (par exemple welcome-user/usr_abc123), afin que les nouvelles tentatives après un redémarrage de processus partagent la même clé ; un UUID aléatoire par opération logique fonctionne aussi. Les SDK Bird génèrent automatiquement une clé UUID pour chaque requête mutative et la réutilisent lors de leurs nouvelles tentatives internes.

Les clés sont rattachées à votre espace de travail, ou à votre organisation pour les points de terminaison au niveau de l'organisation. Une réponse terminée est conservée pendant 3 heures ; une nouvelle tentative après cette fenêtre peut être traitée comme une nouvelle requête. Si le résultat de l'opération d'origine reste inconnu après l'expiration, considérez-la comme non résolue et vérifiez son état avant de renvoyer la requête.

Rejeux

Une nouvelle tentative correspondante dans les trois heures doit aboutir à l'opération d'origine. Lorsque sa réponse est conservée, API renvoie le même code de statut et le même corps sans accepter d'autre opération. Les réponses rejouées portent un en-tête supplémentaire qui vous permet de les distinguer d'un nouveau traitement :

HTTP/1.1 202 Accepted
Idempotency-Replay: true

Les réponses conservées peuvent inclure des rejets 4xx. Utilisez une nouvelle clé lorsque vous corrigez une requête : si son rejet a été conservé, une nouvelle tentative identique le rejoue, et une requête modifiée renvoie 409 E01005 IdempotencyKeyReuse. Les réponses 5xx ne sont pas conservées comme réponses terminées. La garantie d'acceptation unique couvre aussi les nouvelles tentatives après ces erreurs.

Modes d'échec

Réutiliser une clé terminée avec une requête différente est traité comme un bug client : Bird renvoie 409 immédiatement plutôt que de vous remettre silencieusement une réponse qui ne correspond pas à ce que vous avez envoyé. Générez une nouvelle clé pour la nouvelle requête. La comparaison porte sur la méthode, le point de terminaison, le chemin et les paramètres de requête, ainsi que le corps brut de la requête, y compris les espaces JSON. Les téléversements multipart comparent les noms de parties, les noms de fichiers et les contenus ; les délimiteurs et l'ordre des parties n'affectent pas le rejeu.

RequestInProgress signifie qu'une requête concurrente avec la même clé n'a pas encore abouti. C'est généralement le cas lorsqu'un délai d'attente trop court côté client relance la requête alors que la première tentative est encore en cours. Attendez brièvement, puis réessayez avec la même clé et la même requête. Consultez Erreurs pour la réponse d'erreur qui les enveloppe.

Ce qui n'est pas mis en cache

Les réponses 5xx ne sont pas conservées comme réponses terminées. Réessayez dans les trois heures avec un backoff borné, la même clé et une requête identique. La garantie d'acceptation unique s'applique même lorsque la réponse d'origine a été perdue.

Si la protection d'idempotence est indisponible avant l'exécution, l'API renvoie 503 E01033 IdempotencyUnavailable sans exécuter cette tentative. Conservez la clé à chaque nouvelle tentative. Cette erreur ne décrit pas le résultat d'une tentative antérieure avec la même clé.

Conseils pratiques

• Générez une clé par opération logique et réutilisez-la à chaque tentative HTTP de cette opération.
• Réessayez en cas d'erreurs réseau, de délais d'attente dépassés et de 5xx dans les trois heures, avec un backoff exponentiel borné, en conservant la clé et une requête identique.
• Laissez un résultat inconnu non résolu lorsque les nouvelles tentatives sont épuisées ou que la période de conservation expire. Faites un rapprochement avant de soumettre une autre opération, avec l'ancienne clé ou une nouvelle.
• Pour les envois de messages, vérifiez le statut du message afin de confirmer la livraison après l'acceptation.
• Considérez 409 IdempotencyKeyReuse comme un bogue dans votre génération de clés. Ne réessayez pas.
• Les clés sont facultatives sur les mutations. Utilisez-en une lorsque vous avez besoin d'une protection lors des nouvelles tentatives ; omettez-la sur les requêtes GET.

Étapes suivantes

• Référence API de l'idempotence : schémas de l'en-tête et de l'en-tête de réponse
• Concepts SDK : génération automatique des clés et comportement des nouvelles tentatives dans les SDK
• Erreurs : la réponse d'erreur et le catalogue de codes
• Envoi d'e-mails : points de terminaison d'envoi et d'envoi par lot