Limitation du débit
Les limites de débit plafonnent le nombre de requêtes que votre organisation peut effectuer dans une fenêtre de temps. Utilisez les en-têtes de réponse pour cadencer le trafic et le délai de réessai pour récupérer après un rejet de requête.
Comment les limites sont réparties
Votre organisation partage une seule limite régionale par politique, entre ses clés API et ses espaces de travail. Créer une clé supplémentaire n'ajoute pas de capacité. Les organisations distinctes ont des limites séparées.
Chaque requête consomme une politique client. Les politiques produit ont une capacité indépendante : récupérer le statut d'un message ne consomme pas la limite générale de récupération de ressources, et envoyer un e-mail ne consomme pas la limite de création de ressources.
La connexion, la réinitialisation de mot de passe et les autres opérations sensibles en matière de sécurité bénéficient de protections supplémentaires contre les abus. Les vérifications fournisseur et les limites de connexion peuvent également rejeter des requêtes indépendamment des limites de débit de votre plan.
Groupes
Les opérations API ordinaires utilisent ces politiques :
| Politique | Opérations |
|---|---|
| api_get | Récupérer une ressource |
| api_list | Lister ou rechercher une collection |
| api_create | Créer une ressource |
| api_update | Mettre à jour ou upserter une ressource |
| api_delete | Supprimer une ressource |
Les opérations produit utilisent une politique nommée à la place de la politique API ordinaire. Par exemple : email_send, email_batch, sms_send, whatsapp_send, lookup et message_status_read. Les politiques batch comptent les requêtes de soumission ; le nombre de destinataires du batch ne consomme pas d'unités de politique supplémentaires. Consultez envoi batch d'e-mails et envoi batch SMS pour les limites de taille de batch.
L'e-mail REST et la soumission SMTP partagent la capacité email_send. Une soumission DATA SMTP consomme une unité ; l'authentification SMTP non. Si la politique refuse une soumission, le serveur renvoie un 452 4.3.1 temporaire avec un délai de réessai et n'accepte pas le message. Conservez le message en file d'attente et réessayez après ce délai.
Créer une diffusion utilise api_create ; démarrer une diffusion existante utilise api_update. La distribution en arrière-plan aux destinataires ne consomme pas email_send. Les quotas d'envoi et le cadencement de la distribution restent des contrôles séparés.
La politique voice_call limite l'admission des appels entrants et sortants. Une politique épuisée refuse l'appel et enregistre calls_per_second_exceeded ; aucune réponse HTTP n'est impliquée. Consultez Appels rejetés.
Comment votre limite est déterminée
Un remplacement actif au niveau de l'organisation définit votre débit effectif. Sans remplacement, la valeur du plan actif s'applique ; si le plan n'a pas de valeur pour cette politique, la valeur par défaut s'applique. Un plan ou un remplacement peut augmenter ou diminuer le débit. La fenêtre de temps de la politique reste fixe.
Lisez votre quota effectif dans l'en-tête de réponse RateLimit-Policy, qui indique la clé de politique ainsi que le débit et la fenêtre appliqués à cet appel. Si vous avez besoin de capacité supplémentaire, contactez le support avec la clé de politique et le trafic prévu.
En-têtes de réponse
Les évaluations de limitation du débit fournissent deux en-têtes au format IETF Structured Fields (RFC 9651) :
Exemple de code
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35| En-tête | Signification |
|---|---|
| RateLimit-Policy | La politique applicable : q est le quota (unités maximales) et w est la fenêtre en secondes. |
| RateLimit | Votre état actuel : r est le nombre d'unités restantes et t est le nombre de secondes avant la réinitialisation de la fenêtre. |
La chaîne entre guillemets nomme la politique. Dans cet exemple, l'organisation a une limite email_send effective de 1 000 soumissions par 60 secondes, avec 842 restantes et 35 secondes avant la réinitialisation.
Utilisez r et t pour ralentir les requêtes avant de recevoir un 429. La valeur t est un délai relatif en secondes, et non un horodatage Unix.
Lorsque vous atteignez une limite
Votre intégration doit gérer les réponses 429 dans le cadre du fonctionnement normal. Au minimum, respectez Retry-After et réessayez avec un recul exponentiel. Un client qui cadence également ses requêtes en fonction des en-têtes RateLimit en temps réel (voir En-têtes de réponse) évite d'atteindre la limite.
Une politique client épuisée renvoie 429 Too Many Requests avec Retry-After en secondes et des en-têtes de limitation du débit indiquant r=0. Une protection indépendante contre les abus ou une protection fournisseur peut renvoyer 429 même si votre politique client a encore de la capacité. Suivez Retry-After pour décider quand réessayer ; cette valeur peut différer de la valeur t de la politique.
Le corps utilise la réponse d'erreur standard :
Exemple de code
{
"error": {
"type": "rate_limit_error",
"code": "E01003",
"name": "RateLimited",
"message": "Too many requests. Please retry after the period indicated in the Retry-After header.",
"doc_url": "https://bird.com/docs/api/errors/E01003",
"request_id": "req_01ky7qavkff7qr88vadv6bv948"
}
}Branchez sur type: rate_limit_error. Le message lisible peut changer. Lisez la clé de politique et le délai de réessai dans les en-têtes :
async function sendWithBackoff(url, headers, payload, maxAttempts = 5) {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const response = await fetch(url, {
method: "POST",
headers,
body: JSON.stringify(payload),
});
if (response.status !== 429) return response;
const retryAfter = Number(response.headers.get("Retry-After") ?? 2 ** attempt);
await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
}
throw new Error("rate limited after max retries");
}import time
import requests
def send_with_backoff(url, headers, payload, max_attempts=5):
for attempt in range(max_attempts):
response = requests.post(url, headers=headers, json=payload)
if response.status_code != 429:
return response
retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
time.sleep(retry_after)
raise RuntimeError("rate limited after max retries")func sendWithBackoff(req *http.Request, maxAttempts int) (*http.Response, error) {
for attempt := range maxAttempts {
if attempt > 0 && req.Body != nil {
if req.GetBody == nil {
return nil, errors.New("request body cannot be replayed")
}
body, err := req.GetBody()
if err != nil {
return nil, err
}
req.Body = body
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
if resp.StatusCode != http.StatusTooManyRequests {
return resp, nil
}
resp.Body.Close()
wait := 1 << attempt
if s, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil {
wait = s
}
time.Sleep(time.Duration(wait) * time.Second)
}
return nil, errors.New("rate limited after max retries")
}function sendWithBackoff(ClientInterface $http, RequestInterface $request, int $maxAttempts = 5): ResponseInterface
{
for ($attempt = 0; $attempt < $maxAttempts; $attempt++) {
$response = $http->sendRequest($request);
if ($response->getStatusCode() !== 429) {
return $response;
}
$retryAfter = (int) ($response->getHeaderLine('Retry-After') ?: 2 ** $attempt);
sleep($retryAfter);
}
throw new RuntimeException('rate limited after max retries');
}Pour réessayer la même opération, réutilisez sa clé d'idempotence. Conservez le corps de la requête inchangé.
Consultez concepts SDK pour le comportement de réessai automatique et de recul exponentiel.
Mode de défaillance
Le limiteur de débit échoue en mode ouvert : si Bird ne peut pas évaluer une limite, la requête est acceptée plutôt que de recevoir un refus erroné. La limitation du débit protège la capacité du service. L'authentification et l'autorisation restent les frontières de sécurité. Une panne du limiteur côté Bird ne provoque pas de 429.
Étapes suivantes
- Erreurs : la réponse d'erreur et comment brancher selon les types d'erreur
- Idempotence : réessais sûrs pour les requêtes mutantes
- Concepts SDK : comportement de réessai automatique et de recul exponentiel
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideSend 100 emails in one API callComprendre le conceptWhat does SMS mean?Explorer la fonctionnalitéEmail batch sendingSuivre le parcours d'apprentissageBuild your first integration
Obtenir un guide d'implémentation