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 avant nouvelle tentative pour récupérer après le rejet d'une 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 vos plans.

Groupes

Les opérations API ordinaires utilisent ces politiques :

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 avant nouvelle tentative 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

Chaque produit a son propre plan, et chaque plan définit les valeurs des politiques de ce produit : un plan SMS définit sms_send et sms_batch, un plan Voice définit voice_call, et ainsi de suite. Les niveaux supérieurs définissent des valeurs plus élevées. Les politiques partagées, comme le groupe api_*, verify_send, verify_check et message_status_read, peuvent être définies par le plan de n'importe quel produit.

Votre débit effectif pour une politique est déterminé dans cet ordre :

1. Un remplacement actif au niveau de l'organisation, s'il en existe un.
2. La valeur la plus élevée parmi les plans produit actifs de votre organisation qui définissent la politique.
3. La valeur par défaut de la politique, qui correspond au niveau de base du paiement à l'usage.

Un remplacement peut augmenter ou diminuer le débit. La fenêtre de temps de la politique reste fixe, quelle que soit la valeur appliquée.

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. Pour comparer les niveaux, lisez le rate_limits de chaque plan dans le catalogue public des plans (bird billing plans list --commercial-product sms) ou dans le tableau comparatif de la page des tarifs.

Augmenter une limite

Si aucun remplacement au niveau de l'organisation ne s'applique à la politique, passez à un plan supérieur pour le produit auquel elle appartient, sur la page des plans de ce produit sous Billing and payments > Overview. Vérifiez d'abord le rate_limits du plan cible : le nouveau débit ne s'applique que s'il est supérieur à la valeur que vos autres plans vous accordent déjà. Pour une politique partagée, comme api_get ou verify_send, le plan de n'importe quel produit qui définit la politique peut l'augmenter. Le débit plus élevé s'applique dès que le paiement de la mise à niveau a abouti ; Changements de plan et renouvellements détaille le calendrier. Les plans augmentent aussi des quotas qui ne sont pas des limites de débit, comme les appels simultanés Voice.

Un remplacement actif au niveau de l'organisation reste en vigueur quel que soit le plan choisi, et peut être inférieur à la valeur du plan. Si l'en-tête RateLimit-Policy indique un débit inférieur à la valeur publiée de votre plan, contactez le support en indiquant la clé de politique pour faire examiner le remplacement.

Si vous avez besoin de plus que ce que fournit le plan publié le plus élevé, contactez l'équipe commerciale en indiquant 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) :

RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35

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 :

{
  "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 avant nouvelle tentative 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 nouvelle tentative 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 traitée au lieu d'être refusée à tort. 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 : nouvelles tentatives sûres pour les requêtes qui modifient des données
• Concepts SDK : comportement de nouvelle tentative automatique et de recul exponentiel