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, und die Retry-Verzögerung, um sich von einer abgelehnten Anfrage zu erholen.
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 Ihres Plans ablehnen.
Gruppen
Gewöhnliche API-Operationen verwenden diese Richtlinien:
| Richtlinie | Operationen |
|---|---|
| api_get | Eine Ressource abrufen |
| api_list | Eine Sammlung auflisten oder suchen |
| api_create | Eine Ressource erstellen |
| api_update | Eine Ressource aktualisieren oder upserten |
| api_delete | Eine Ressource löschen |
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
Eine aktive organisationsspezifische Überschreibung legt Ihre effektive Rate fest. Ohne Überschreibung gilt der Wert Ihres aktiven Plans; hat der Plan keinen Wert für diese Richtlinie, gilt der Standardwert. Ein Plan oder eine Überschreibung kann die Rate erhöhen oder senken. Das Zeitfenster der Richtlinie bleibt fest.
Lesen Sie Ihr effektives Kontingent aus dem RateLimit-Policy-Antwort-Header ab, der den Richtlinien-Key zusammen mit der Rate und dem Zeitfenster enthält, die für diesen Aufruf galten. Wenn Sie zusätzliche Kapazität benötigen, kontaktieren Sie den Support mit dem Richtlinien-Key und dem erwarteten Datenverkehr.
Antwort-Header
Auswertungen der Begrenzung der Anfragerate liefern zwei Header im IETF-Structured-Fields-Format (RFC 9651):
Codebeispiel
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35| Header | Bedeutung |
|---|---|
| RateLimit-Policy | Die geltende Richtlinie: q ist das Kontingent (maximale Einheiten) und w ist das Zeitfenster in Sekunden. |
| RateLimit | Ihr aktueller Status: r ist die Anzahl verbleibender Einheiten und t ist die Anzahl der Sekunden bis zum Zurücksetzen des Zeitfensters. |
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:
Codebeispiel
{
"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 das Retry-Timing aus den Headern:
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.
Siehe SDK-Konzepte für automatisches Retry- und Backoff-Verhalten.
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: automatisches Retry- und Backoff-Verhalten
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenSend 100 emails in one API callDas Konzept verstehenWhat does SMS mean?Die Funktion erkundenEmail batch sendingDem Lernpfad folgenBuild your first integration
Implementierungs-Briefing erhalten