Un expéditeur actif peut épuiser son budget de requêtes avant que tous ses messages soient mis en file d'attente. Lire le quota restant lui permet de ralentir avant que d'autres appels soient refusés.
Comment Bird détermine-t-il ma limite ?
Bird applique un débit de base, toute augmentation liée au plan, puis tout override pour le groupe concerné. Un override remplace les autres valeurs.
Les endpoints associés partagent un groupe. Épuiser un groupe d'envoi n'épuise pas en soi les groupes distincts utilisés pour lire les statuts ou gérer les webhooks.
La portée de chaque budget dépend de l'opération :
| Groupe | Qui partage le budget ? |
|---|---|
| Envois produit | Toutes les credentials de l'organisation pour ce produit. |
| Lectures, listes et écritures de gestion | Requêtes provenant de la même credential active au sein de l'organisation. |
| Connexion ou réinitialisation de mot de passe non authentifiée | Requêtes provenant de la même adresse IP cliente. |
Les limites non authentifiées utilisent des seuils fixes. Consultez le guide de limitation du débit pour les groupes assignés à chaque endpoint.
Les limites d'envoi comptent les requêtes, pas les destinataires. Une requête batch peut mettre en file d'attente plusieurs messages. Son groupe peut avoir un quota différent.
Comparez les quotas en vigueur et le nombre de destinataires que vous pouvez regrouper avant de changer d'endpoint. Un batch contenant un seul destinataire peut n'apporter aucun gain de débit.
Comment lire les en-têtes de réponse ?
Lisez RateLimit-Policy pour le quota et la fenêtre, puis RateLimit pour les requêtes restantes et le temps avant réinitialisation.
Par exemple :
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35Cet exemple autorise 1 000 requêtes par fenêtre de 60 secondes. Il reste 842 requêtes, avec 35 secondes avant réinitialisation.
Les nombres illustrent les en-têtes. Ils ne constituent pas un quota garanti. Lisez les valeurs renvoyées à votre client.
| Champ | Signification |
|---|---|
| Nom entre guillemets | Le groupe auquel la politique s'applique. |
q | Requêtes autorisées par fenêtre. |
w | Durée de la fenêtre en secondes. |
r | Requêtes restantes. |
t | Secondes avant réinitialisation, pas un horodatage. |
Une réponse peut contenir plus d'une politique. Tenez compte de chaque politique applicable pour planifier la requête suivante.
Que renvoie un échec de limitation du débit ?
Une limite API épuisée renvoie 429 Too Many Requests avec Retry-After en secondes. Les en-têtes de limitation du débit identifient le groupe épuisé. Son quota restant est r=0.
La réponse d'erreur inclut les champs suivants :
{
"error": {
"type": "rate_limit_error",
"code": "E01003",
"name": "RateLimited"
}
}Filtrez sur le type ou le code dans votre gestionnaire. Le message lisible peut changer sans modifier l'action de récupération.
Comment mon client doit-il gérer une 429 ?
Attendez la valeur de Retry-After, puis réessayez avec une politique de backoff bornée. Conservez la même clé d'idempotence lorsque vous répétez la même écriture.
Coordonnez les workers utilisant le même budget de groupe. La dernière réponse d'un worker ne peut pas tenir compte des requêtes soumises par d'autres workers entre-temps.
Ralentissez à mesure que le quota restant diminue. Conservez le chemin de réessai pour le trafic concurrent. Le cadençage réduit les échecs mais ne peut pas garantir qu'aucun appel ne recevra une 429.
Les SDK Bird gèrent les réessais 429 et Retry-After. Ils ne coordonnent pas une file d'attente partagée entre tous vos processus.
Si le quota reste trop bas pour la charge de travail, contactez Bird pour un override. Créer davantage de clés n'augmente pas la limite d'envoi à l'échelle de l'organisation.
Une requête limitée a-t-elle effectué du travail ?
Bird rejette une requête limitée avant d'effectuer le travail demandé. Ce rejet ne consomme pas sa clé d'idempotence. Réessayez avec la même clé après avoir attendu.
Le limiteur laisse passer les requêtes s'il ne peut pas évaluer la limite. Un problème d'évaluation des quotas ne produit donc pas en soi une 429.
Conservez la gestion de l'idempotence pour les autres échecs également. Une erreur serveur ou une réponse perdue peut survenir après le début d'une écriture.
En bref
Lisez le quota dans les réponses.
La limite applicable dépend du groupe, du plan et d'un éventuel override. Un nombre fixe codé en dur peut devenir inexact.
Coordonnez les expéditeurs qui partagent un quota.
Les limites d'envoi s'appliquent à l'échelle de l'organisation : des clés distinctes ne créent pas des budgets d'envoi distincts.
Attendez avant de réessayer après une 429.
Retry-Afterindique le délai en secondes. Limitez vos tentatives. Conservez la même clé d'idempotence pour la même écriture.Traitez les en-têtes comme un état partagé.
Les requêtes restantes peuvent être consommées par d'autres workers : le cadençage réduit les échecs de limitation du débit sans les éliminer.