Beperking van het aantal verzoeken
Beperkingen van het aantal verzoeken begrenzen hoeveel verzoeken je organisatie in een tijdvenster kan doen. Gebruik de responseheaders om verkeer te doseren en de retry-vertraging om te herstellen van een geweigerd verzoek.
Hoe limieten worden bepaald
Je organisatie deelt één regionale limiet per policy, over al zijn API-keys en werkruimtes. Een extra key aanmaken voegt geen capaciteit toe. Verschillende organisaties hebben afzonderlijke limieten.
Elk verzoek verbruikt één klant-policy. Productpolicies hebben onafhankelijke capaciteit: het ophalen van de berichtstatus verbruikt niet de algemene limiet voor het ophalen van resources, en het verzenden van een e-mail verbruikt niet de limiet voor het aanmaken van resources.
Login, wachtwoordherstel en andere beveiligingsgevoelige bewerkingen hebben aanvullende misbruikbeschermingen. Leverancierscontroles en verbindingslimieten kunnen verzoeken ook onafhankelijk van de beperkingen van je plan weigeren.
Groepen
Gewone API-bewerkingen gebruiken deze policies:
| Policy | Bewerkingen |
|---|---|
| api_get | Eén resource ophalen |
| api_list | Een collectie ophalen of doorzoeken |
| api_create | Een resource aanmaken |
| api_update | Een resource bijwerken of upserten |
| api_delete | Een resource verwijderen |
Productbewerkingen gebruiken een benoemde policy in plaats van de gewone API-policy. Voorbeelden zijn email_send, email_batch, sms_send, whatsapp_send, lookup en message_status_read. Batchpolicies tellen indieningsverzoeken; het aantal ontvangers in de batch verbruikt geen extra policy-eenheden. Zie e-mail batchverzending en SMS batchverzending voor batchgrootte-limieten.
REST-e-mail en SMTP-indiening delen email_send-capaciteit. Een SMTP DATA-indiening verbruikt één eenheid; SMTP-authenticatie niet. Als de policy een indiening weigert, retourneert de server een tijdelijke 452 4.3.1 met een retry-vertraging en accepteert het bericht niet. Houd het bericht in de wachtrij en probeer het opnieuw na die vertraging.
Het aanmaken van een broadcast gebruikt api_create; het starten van een bestaande broadcast gebruikt api_update. Achtergrondaflevering aan de ontvangers verbruikt geen email_send. Verzendtoewijzingen en afleverdosering blijven afzonderlijke instellingen.
De voice_call-policy beperkt inkomende en uitgaande gesprekstoelating. Een uitgeputte policy weigert het gesprek en registreert calls_per_second_exceeded; er is geen HTTP-response bij betrokken. Zie Geweigerde gesprekken.
Hoe je limiet wordt bepaald
Een actieve organisatie-override stelt je effectieve snelheid in. Zonder override geldt de waarde van je actieve plan; als het plan geen waarde heeft voor die policy, geldt de standaardwaarde. Een plan of override kan de snelheid verhogen of verlagen. Het tijdvenster van de policy blijft vast.
Lees je effectieve quotum af uit de RateLimit-Policy-responseheader, die de policy-key vermeldt samen met de snelheid en het venster die op dat verzoek van toepassing waren. Als je extra capaciteit nodig hebt, neem dan contact op met support met de policy-key en het verwachte verkeer.
Responseheaders
Evaluaties van de beperking van het aantal verzoeken leveren twee headers in het IETF Structured Fields-formaat (RFC 9651):
Codevoorbeeld
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35| Header | Betekenis |
|---|---|
| RateLimit-Policy | De policy die van toepassing is: q is het quotum (maximale eenheden) en w is het venster in seconden. |
| RateLimit | Je huidige status: r is het aantal resterende eenheden en t is het aantal seconden tot het venster reset. |
De string tussen aanhalingstekens benoemt de policy. In dit voorbeeld heeft de organisatie een effectieve email_send-limiet van 1000 indieningen per 60 seconden, met 842 resterend en 35 seconden tot reset.
Gebruik r en t om verzoeken te vertragen voordat je een 429 ontvangt. De t-waarde is een relatieve vertraging in seconden, geen Unix-timestamp.
Wanneer je een limiet bereikt
Je integratie moet 429-responses als onderdeel van de normale werking afhandelen. Respecteer minimaal Retry-After en probeer opnieuw met backoff. Een client die zichzelf ook doseert op basis van de actuele RateLimit-headers (zie Responseheaders) voorkomt dat de limiet wordt bereikt.
Een uitgeputte klant-policy retourneert 429 Too Many Requests met Retry-After in seconden en rate-limit-headers met r=0. Een onafhankelijke misbruik- of leveranciersbescherming kan 429 retourneren, ook als je klant-policy nog resterende capaciteit heeft. Volg Retry-After om te bepalen wanneer je opnieuw moet proberen; deze kan afwijken van de t-waarde van de policy.
De body gebruikt het standaard foutantwoord:
Codevoorbeeld
{
"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"
}
}Branch op type: rate_limit_error. Het leesbare bericht kan veranderen. Lees de policy-key en retry-timing af uit de headers:
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');
}Hergebruik bij retries van dezelfde bewerking de bijbehorende idempotency-key. Houd de requestbody ongewijzigd.
Zie SDK-concepten voor automatisch opnieuw proberen en backoff-gedrag.
Faalgedrag
De rate limiter faalt open: als Bird een limiet niet kan evalueren, gaat het verzoek door in plaats van een onterechte weigering te ontvangen. Beperking van het aantal verzoeken beschermt servicecapaciteit. Authenticatie en autorisatie blijven de beveiligingsgrenzen. Een Bird-side limiter-storing veroorzaakt geen 429.
Volgende stappen
- Fouten: het foutantwoord en hoe je op fouttypes brancht
- Idempotency: veilige retries voor muterende verzoeken
- SDK-concepten: automatisch opnieuw proberen en backoff-gedrag
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Bekijk de gidsSend 100 emails in one API callBegrijp het conceptWhat does SMS mean?Ontdek de mogelijkheidEmail batch sendingVolg het leerpadBuild your first integration
Ontvang een implementatieoverzicht