Czym jest ograniczanie liczby żądań w API i jak obsłużyć błąd 429?

Intensywnie wysyłający klient może wyczerpać swój budżet żądań, zanim wszystkie wiadomości trafią do kolejki. Odczytywanie pozostałego limitu pozwala zwolnić, zanim kolejne wywołania zostaną odrzucone.

Jak Bird ustala mój limit?

Bird stosuje bazowy limit, ewentualne podwyższenie z planu, a następnie ewentualne nadpisanie dla danej grupy. Nadpisanie zastępuje pozostałe wartości.

Powiązane endpointy współdzielą grupę. Wyczerpanie grupy wysyłki nie wyczerpuje samo w sobie osobnych grup służących do odczytu statusu czy zarządzania webhookami.

Zakres każdego budżetu zależy od operacji:

Limity nieuwierzytelnionych żądań mają stałe progi. Grupy przypisane do poszczególnych endpointów znajdziesz w przewodniku po limitach.

Limity wysyłki liczą żądania, nie odbiorców. Żądanie wsadowe może zakolejkować kilka wiadomości. Jego grupa może mieć inny limit.

Porównaj aktualne limity z liczbą odbiorców, których możesz zgrupować, zanim zmienisz endpoint. Żądanie wsadowe z jednym odbiorcą może nie dać żadnego zysku w przepustowości.

Jak odczytać nagłówki odpowiedzi?

Odczytaj RateLimit-Policy, aby poznać limit i okno czasowe, a następnie RateLimit, aby poznać pozostałe żądania i czas do resetu.

Na przykład:

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

Ten przykład dopuszcza 1000 żądań w 60-sekundowym oknie. Pozostaje 842 żądań, a do resetu zostało 35 sekund.

Liczby ilustrują nagłówki. Nie są obiecanym limitem. Odczytuj wartości zwracane do Twojego klienta.

Odpowiedź może zawierać więcej niż jedną politykę. Uwzględnij każdą obowiązującą politykę, planując kolejne żądanie.

Co zwraca odmowa z powodu limitu?

Wyczerpany limit API zwraca 429 Too Many Requests z Retry-After wyrażonym w sekundach. Nagłówki limitu wskazują wyczerpaną grupę. Jej pozostały limit wynosi r=0.

Odpowiedź z błędem zawiera następujące pola:

{
  "error": {
    "type": "rate_limit_error",
    "code": "E01003",
    "name": "RateLimited"
  }
}

Dopasowuj typ lub kod w swoim handlerze. Czytelny dla człowieka komunikat może się zmienić bez zmiany sposobu obsługi błędu.

Jak mój klient powinien obsłużyć 429?

Poczekaj na Retry-After, a następnie ponów żądanie ze strategią ograniczonego backoffu. Zachowaj ten sam klucz idempotentności, powtarzając ten sam zapis.

Koordynuj procesy korzystające z tego samego budżetu grupy. Ostatnia odpowiedź procesu nie uwzględnia żądań, które inne procesy wysłały od tego czasu.

Zwalniaj w miarę spadku pozostałego limitu. Zachowaj ścieżkę ponawiania dla ruchu współbieżnego. Regulowanie tempa zmniejsza liczbę odmów, ale nie gwarantuje, że żadne wywołanie nie otrzyma 429.

SDK Bird obsługują ponawianie po 429 i Retry-After. Nie koordynują współdzielonej kolejki między wszystkimi Twoimi procesami.

Jeśli limit jest zbyt niski dla obciążenia, skontaktuj się z Bird w sprawie nadpisania. Tworzenie kolejnych kluczy nie zwiększa limitu wysyłki obowiązującego w całej organizacji.

Czy żądanie odrzucone przez limiter wykonało jakąkolwiek pracę?

Bird odrzuca żądanie przekraczające limit, zanim wykona żądaną operację. To odrzucenie nie zużywa klucza idempotentności. Ponów żądanie z tym samym kluczem po odczekaniu.

Limiter przepuszcza żądania, jeśli nie może ocenić limitu. Problem z oceną limitów sam w sobie nie powoduje więc błędu 429.

Zachowaj obsługę idempotentności również dla innych błędów. Błąd serwera lub utracona odpowiedź mogą wystąpić po rozpoczęciu zapisu.