Begrenzung der Anfragerate

Begrenzungen der Anfragerate legen fest, wie viele Anfragen Ihre Organisation in einem Zeitfenster senden kann. Nutzen Sie die Antwort-Header, um den Datenverkehr zu steuern. Warten Sie nach einer abgelehnten Anfrage die angegebene Verzögerung ab und versuchen Sie es dann erneut.

Wie Limits zugeordnet werden

Ihre Organisation teilt sich ein regionales Limit pro Richtlinie über alle ihre API-Keys und Workspaces hinweg. Ein weiterer Key erhöht die Kapazität nicht. Verschiedene Organisationen haben getrennte Limits.

Jede Anfrage verbraucht eine Kunden-Richtlinie. Produkt-Richtlinien haben unabhängige Kapazität: Das Abrufen des Nachrichtenstatus verbraucht nicht das allgemeine Limit für Ressourcenabruf, und das Senden einer E-Mail verbraucht nicht das Limit für Ressourcenerstellung.

Login, Passwortzurücksetzung und andere sicherheitsrelevante Vorgänge haben zusätzliche Missbrauchsschutzmaßnahmen. Anbieterprüfungen und Verbindungslimits können Anfragen ebenfalls unabhängig von den Limits Ihrer Pläne ablehnen.

Gruppen

Gewöhnliche API-Operationen verwenden diese Richtlinien:

Produktoperationen verwenden eine benannte Richtlinie anstelle der gewöhnlichen API-Richtlinie. Beispiele sind email_send, email_batch, sms_send, whatsapp_send, lookup und message_status_read. Batch-Richtlinien zählen Übermittlungsanfragen; die Empfängeranzahl des Batches verbraucht keine zusätzlichen Richtlinieneinheiten. Siehe E-Mail-Batch-Versand und SMS-Batch-Versand für Batch-Größenlimits.

REST-E-Mail und SMTP-Übermittlung teilen sich email_send-Kapazität. Eine SMTP-DATA-Übermittlung verbraucht eine Einheit; SMTP-Authentifizierung nicht. Wenn die Richtlinie eine Übermittlung ablehnt, gibt der Server einen temporären 452 4.3.1 mit einer Retry-Verzögerung zurück und nimmt die Nachricht nicht an. Halten Sie die Nachricht in der Warteschlange und versuchen Sie es nach dieser Verzögerung erneut.

Das Erstellen eines Broadcasts verwendet api_create; das Starten eines bestehenden Broadcasts verwendet api_update. Die Hintergrundzustellung an die Empfänger verbraucht kein email_send. Versandkontingente und Zustellungsdrosselung bleiben separate Steuerungen.

Die voice_call-Richtlinie begrenzt die Annahme ein- und ausgehender Anrufe. Eine erschöpfte Richtlinie lehnt den Anruf ab und zeichnet calls_per_second_exceeded auf; keine HTTP-Antwort ist beteiligt. Siehe Abgelehnte Anrufe.

Wie Ihr Limit bestimmt wird

Jedes Produkt hat einen eigenen Plan, und jeder Plan legt Werte für die Richtlinien dieses Produkts fest: Ein SMS-Plan legt sms_send und sms_batch fest, ein Voice-Plan legt voice_call fest und so weiter. Höhere Stufen legen höhere Werte fest. Gemeinsame Richtlinien wie die api_*-Gruppe, verify_send, verify_check und message_status_read kann der Plan jedes Produkts festlegen.

Ihre effektive Rate für eine Richtlinie wird in dieser Reihenfolge bestimmt:

1. Eine aktive organisationsspezifische Überschreibung, sofern vorhanden.
2. Der höchste Wert unter den aktiven Produktplänen Ihrer Organisation, die die Richtlinie festlegen.
3. Der Standardwert der Richtlinie, also die Basis für Pay-as-you-go.

Eine Überschreibung kann die Rate erhöhen oder senken. Das Zeitfenster der Richtlinie bleibt unabhängig vom geltenden Wert gleich.

Lesen Sie Ihr effektives Kontingent aus dem RateLimit-Policy-Antwort-Header ab. Er enthält den Richtlinien-Key zusammen mit der Rate und dem Zeitfenster, die für diesen Aufruf galten. Um Stufen zu vergleichen, lesen Sie die rate_limits jedes Plans aus dem öffentlichen Plankatalog (bird billing plans list --commercial-product sms) oder aus der Vergleichstabelle auf der Preisseite ab.

Ein Limit erhöhen

Wenn für die Richtlinie keine organisationsspezifische Überschreibung gilt, stufen Sie den Plan des zugehörigen Produkts auf dessen Planseite unter Billing and payments > Overview hoch. Prüfen Sie zuerst den Wert rate_limits des Zielplans: Die neue Rate gilt nur, wenn sie höher ist als der Wert, den Ihre anderen Pläne bereits festlegen. Eine gemeinsame Richtlinie wie api_get oder verify_send kann der Plan jedes Produkts erhöhen, der diese Richtlinie festlegt. Die höhere Rate gilt, sobald die Zahlung für das Upgrade erfolgreich ist; den Zeitpunkt beschreibt Planänderungen und Verlängerungen. Pläne erhöhen auch Kontingente, die keine Begrenzungen der Anfragerate sind, etwa gleichzeitige Voice-Anrufe.

Eine aktive organisationsspezifische Überschreibung bleibt unabhängig vom gewählten Plan wirksam und kann niedriger sein als der Wert des Plans. Wenn der RateLimit-Policy-Header eine niedrigere Rate als den veröffentlichten Wert Ihres Plans zeigt, wenden Sie sich mit dem Richtlinien-Key an den Support, damit dieser die Überschreibung prüft.

Wenn Sie mehr benötigen, als der höchste veröffentlichte Plan bietet, kontaktieren Sie den Vertrieb und nennen Sie den Richtlinien-Key und Ihren erwarteten Datenverkehr.

Antwort-Header

Auswertungen der Begrenzung der Anfragerate liefern zwei Header im IETF-Structured-Fields-Format (RFC 9651):

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

Die Zeichenkette in Anführungszeichen benennt die Richtlinie. In diesem Beispiel hat die Organisation ein effektives email_send-Limit von 1.000 Übermittlungen pro 60 Sekunden, mit 842 verbleibend und 35 Sekunden bis zum Zurücksetzen.

Verwenden Sie r und t, um Anfragen zu drosseln, bevor Sie einen 429 erhalten. Der t-Wert ist eine relative Verzögerung in Sekunden, kein Unix-Zeitstempel.

Wenn Sie ein Limit erreichen

Ihre Integration muss 429-Antworten als Teil des normalen Betriebs behandeln. Beachten Sie mindestens Retry-After und versuchen Sie es mit Backoff erneut. Ein Client, der sich zusätzlich an den aktuellen RateLimit-Headern orientiert (siehe Antwort-Header), vermeidet das Erreichen des Limits.

Eine erschöpfte Kunden-Richtlinie gibt 429 Too Many Requests mit Retry-After in Sekunden und Antwort-Headern mit r=0 zurück. Ein unabhängiger Missbrauchs- oder Anbieterschutz kann 429 zurückgeben, selbst wenn Ihre Kunden-Richtlinie noch Kapazität hat. Folgen Sie Retry-After, um zu entscheiden, wann Sie es erneut versuchen; dieser Wert kann vom t-Wert der Richtlinie abweichen.

Der Body verwendet die Standard-Fehlerantwort:

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

Verzweigen Sie anhand von type: rate_limit_error. Die menschenlesbare Nachricht kann sich ändern. Lesen Sie den Richtlinien-Key und den Zeitpunkt für den erneuten Versuch aus den Headern ab:

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');
}

Verwenden Sie bei erneuten Versuchen derselben Operation den bestehenden Idempotenz-Key wieder. Lassen Sie den Request-Body unverändert.

Unter SDK-Konzepte erfahren Sie, wie der Client automatisch erneut versucht und Backoff anwendet.

Fehlermodus

Der Rate-Limiter ist fail-open: Wenn Bird ein Limit nicht auswerten kann, wird die Anfrage durchgelassen, anstatt eine fehlerhafte Ablehnung zu erzeugen. Die Begrenzung der Anfragerate schützt die Dienstkapazität. Authentifizierung und Autorisierung bleiben die Sicherheitsgrenzen. Ein Ausfall des Limiters auf Bird-Seite verursacht keinen 429.

Nächste Schritte

• Fehler: die Fehlerantwort und wie Sie anhand von Fehlertypen verzweigen
• Idempotenz: sichere erneute Versuche für mutierende Anfragen
• SDK-Konzepte: wie der Client automatisch erneut versucht und Backoff anwendet