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 vertraging voor opnieuw proberen 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 weigeren, los van de limieten van je plannen.

Groepen

Gewone API-bewerkingen gebruiken deze policies:

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

Elk product heeft een eigen plan, en elk plan stelt waarden in voor de policies van dat product: een SMS-plan stelt sms_send en sms_batch in, een Voice-plan stelt voice_call in, enzovoort. Hogere niveaus stellen hogere waarden in. Gedeelde policies, zoals de groep api_*, verify_send, verify_check en message_status_read, kunnen door het plan van elk product worden ingesteld.

Je effectieve snelheid voor een policy wordt in deze volgorde bepaald:

1. Een actieve organisatie-override, als die bestaat.
2. De hoogste waarde van de actieve productplannen van je organisatie die de policy instellen.
3. De standaardwaarde van de policy, de pay-as-you-go-basis.

Een override kan de snelheid verhogen of verlagen. Het tijdvenster van de policy blijft vast, welke waarde ook geldt.

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. Om niveaus te vergelijken, lees je de rate_limits van elk plan af uit de openbare plancatalogus (bird billing plans list --commercial-product sms) of uit de vergelijkingstabel op de prijspagina.

Een limiet verhogen

Als er geen organisatie-override op de policy van toepassing is, upgrade je het plan van het product waar de policy bij hoort, op de planpagina van dat product onder Billing and payments > Overview. Controleer eerst de rate_limits van het doelplan: de nieuwe snelheid geldt alleen als die hoger is dan de waarde die je andere plannen al geven. Een gedeelde policy, zoals api_get of verify_send, kan worden verhoogd door het plan van elk product dat de policy instelt. De hogere snelheid geldt zodra de betaling voor de upgrade is gelukt; Planwijzigingen en verlengingen beschrijft de timing. Plannen verhogen ook quota die geen beperkingen van het aantal verzoeken zijn, zoals gelijktijdige gesprekken bij Voice.

Een actieve organisatie-override blijft van kracht, welk plan je ook kiest, en kan lager zijn dan de waarde van het plan. Toont de RateLimit-Policy-header een snelheid onder de gepubliceerde waarde van je plan, neem dan contact op met support en vermeld de policy-key, zodat de override kan worden beoordeeld.

Heb je meer nodig dan het hoogste gepubliceerde plan biedt, neem dan contact op met sales en vermeld de policy-key en je verwachte verkeer.

Responseheaders

Evaluaties van de beperking van het aantal verzoeken leveren twee headers in het IETF Structured Fields-formaat (RFC 9651):

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

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:

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

Bepaal je afhandeling op basis van type: rate_limit_error. Het leesbare bericht kan veranderen. Lees de policy-key en het moment om opnieuw te proberen 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 je afhandeling op fouttypes baseert
• Idempotency: veilig opnieuw proberen bij muterende verzoeken
• SDK-concepten: automatisch opnieuw proberen en backoff-gedrag