HubSpot API – limity i rate limiting. Jak projektować integracje, które nie zatrzymają Twojego biznesu?

W logach pojawia się

429 Too Many Requests

Czym jest rate limiting w HubSpot?

Każde wywołanie API to żądanie wysyłane przez zewnętrzny system do HubSpot.

Może to być na przykład:

Jeżeli integracja wykonuje kilka takich operacji dziennie, limity praktycznie nie są zauważalne.

Problem zaczyna się wtedy, gdy system obsługuje setki lub tysiące rekordów albo kilka aplikacji jednocześnie korzysta z tego samego konta HubSpot.

HubSpot ogranicza liczbę zapytań, które można wykonać w określonym czasie.

Jakie są limity HubSpot API?

W praktyce warto zwrócić uwagę przede wszystkim na dwa rodzaje limitów: krótkookresowy oraz dzienny.

Dla prywatnie dystrybuowanych aplikacji ogólne limity wyglądają następująco:

Porównanie limitów według planu HubSpot

W przypadku API Limit Increase limit krótkookresowy może zostać zwiększony, podobnie jak dostępny limit dzienny.

Najważniejsza różnica wygląda jednak tak:

I właśnie ten drugi element potrafi powodować niespodzianki.

Czy kilka integracji współdzieli limit HubSpot API?

Wyobraźmy sobie firmę posiadającą:

Każda z nich osobno może generować rozsądną liczbę zapytań.

Problem pojawia się wtedy, gdy patrzymy na cały ekosystem.

Jeżeli kilka integracji intensywnie synchronizuje dane, kolejna może zacząć otrzymywać błędy mimo tego, że sama wykonuje stosunkowo niewiele operacji.

Dlatego projektując architekturę HubSpot, nie patrzymy na pojedynczy skrypt.

429 Too Many Requests – co oznacza ten błąd w HubSpot?

Jeżeli aplikacja przekroczy dostępny limit, HubSpot może zwrócić:

Nie powinno to automatycznie oznaczać awarii integracji.

W praktyce oznacza:

I tutaj bardzo łatwo odróżnić integrację przygotowaną do pracy produkcyjnej od prostego skryptu.

Najgorszy możliwy mechanizm wygląda tak:

System sam pogłębia problem, przed którym próbuje się obronić.

Retry i exponential backoff – jak obsłużyć błąd 429?

Integracja powinna posiadać mechanizm ponawiania nieudanych operacji.

Nie oznacza to jednak próbowania ponownie co sekundę aż do skutku.

Dobrym rozwiązaniem jest exponential backoff.

Przykładowo:

Przerwa pomiędzy kolejnymi próbami stopniowo rośnie.

W systemach działających na większą skalę warto również dodać tzw. jitter, czyli niewielkie losowe przesunięcie czasu ponowienia.

Jeżeli 20 workerów jednocześnie otrzyma 429 i wszystkie spróbują ponownie dokładnie po dwóch sekundach, HubSpot ponownie otrzyma falę requestów w tym samym momencie.

Kolejka zadań zamiast wyścigu requestów

Przy większych automatyzacjach znacznie bezpieczniejszy model wygląda tak:

Jeżeli HubSpot chwilowo nie może przyjąć kolejnego zapytania:

Dzięki temu proces biznesowy nie znika tylko dlatego, że API przez kilka sekund nie przyjęło kolejnego requestu.

To szczególnie ważne przy procesach takich jak:

Batch API – czy naprawdę potrzebujesz requestu dla każdego rekordu?

Drugim częstym problemem nie jest sam limit.

Jest nim sposób napisania integracji.

Załóżmy, że musimy zaktualizować 1000 kontaktów.

Najprostsze rozwiązanie wygląda tak:

Bardzo szybko generujemy tysiące operacji.

HubSpot udostępnia jednak endpointy batchowe, dzięki którym wiele rekordów można obsłużyć w jednym żądaniu.

Dlatego przy projektowaniu większych integracji zawsze warto sprawdzić:

Czasem kilkaset wywołań można zastąpić kilkoma.

Oznacza to:

Cache – najdroższy request to ten, którego nie trzeba było wykonać

Wyobraźmy sobie aplikację, która przy każdej operacji pobiera z HubSpot:

Jeżeli dane praktycznie się nie zmieniają, nie ma sensu pobierać ich setki razy.

Można wykorzystać cache.

To jedna z najprostszych metod ograniczenia liczby zapytań.

Webhook czy polling?

Kolejny klasyczny przykład.

Chcemy dowiedzieć się, czy kontakt został zmieniony.

Możemy sprawdzać HubSpot regularnie:

To polling.

System nie wie, czy cokolwiek się wydarzyło, więc cały czas pyta.

Przy jednej integracji może nie być problemu. Przy tysiącach rekordów robi się kosztownie.

Alternatywą są webhooki.

Zamiast regularnie pytać system:

czekamy, aż system sam poinformuje nas o zmianie.

CRM Search API ma własne limity

Warto zwrócić szczególną uwagę na endpointy wyszukiwania CRM.

CRM Search API posiada bardziej restrykcyjne limity niż ogólne API HubSpot.

To istotne, ponieważ wyszukiwanie rekordów bardzo łatwo trafia do pętli.

Przykład:

Przy większym imporcie szybko może okazać się, że to właśnie Search API, a nie ogólny limit konta, jest pierwszym wąskim gardłem.

Czy zwiększenie limitu HubSpot API rozwiązuje problem?

Czasami tak.

HubSpot oferuje możliwość zwiększenia dostępnych limitów API.

Jeżeli aplikacja wykonuje 500 000 requestów, z których 300 000 jest niepotrzebnych, większy limit nie naprawia architektury.

Pozwala jej tylko dłużej działać w nieefektywny sposób.

Zanim zwiększymy limit, warto sprawdzić:

Dopiero później warto analizować zwiększenie dostępnej przepustowości.

Monitoring HubSpot API powinien być częścią integracji

Dobrze zaprojektowana integracja nie czeka na moment, w którym biznes zauważy problem.

HubSpot zwraca między innymi nagłówki pozwalające kontrolować dostępny limit:

Można dzięki nim kontrolować, ile zapytań pozostało w aktualnym oknie czasowym.

HubSpot udostępnia również monitoring wykorzystania API bezpośrednio w platformie.

Dzięki temu można obserwować trendy, wykrywać nietypowe skoki wykorzystania i reagować zanim integracje zaczną otrzymywać błędy 429.

Bo jeżeli o przekroczeniu limitu dowiadujemy się od handlowca, który mówi:

to monitoring zadziałał zdecydowanie za późno.

Rate limiting to nie problem API, tylko architektury.

Limitów nie da się całkowicie wyeliminować.

Można natomiast zaprojektować system tak, aby użytkownik praktycznie ich nie zauważał.

Dobra integracja HubSpot powinna posiadać:

Wtedy chwilowe przekroczenie limitu nie zatrzymuje procesu.

Zadanie trafia do kolejki, system zwalnia, wykonuje je ponownie i kontynuuje pracę.

Bez Excela. Bez ręcznego poprawiania danych. Bez osoby sprawdzającej codziennie rano, czy „integracja nadal działa”.

Integracja HubSpot powinna skalować się razem z biznesem

Integrację można zbudować tak, aby działała dzisiaj.

Można też zaprojektować ją tak, aby nadal działała wtedy, gdy liczba klientów, transakcji i automatyzacji wzrośnie pięciokrotnie.

W Velmanta projektujemy integracje HubSpot jako część całej architektury procesów firmy.

Analizujemy nie tylko jak połączyć system A z systemem B, ale przede wszystkim jak dane mają przepływać przez organizację, żeby proces działał stabilnie również wtedy, gdy firma zwiększy skalę.

Bo dobrze zaprojektowane API powinno być niewidoczne.

Najczęściej zadawane pytania o limity HubSpot API