Limites da API da HubSpot: por que o 429 acontece e como conviver com ele

Toda integração com a API da HubSpot tem um rito de passagem, e ele costuma acontecer no pior horário possível. Numa madrugada de carga pesada, ou bem no meio de uma campanha, a rotina que rodava redondinha começa a devolver um erro 429 que ninguém entende. O primeiro instinto é achar que algo quebrou, que o código tem um bug novo, que a HubSpot caiu. Quase nunca é isso.

O 429 não é um defeito da sua integração. É o controle de taxa da plataforma fazendo exatamente o trabalho dele: avisar que você passou do número de requisições permitido naquele período. Toda API séria tem esse mecanismo, e a HubSpot não é exceção. O que separa uma integração frágil de uma robusta não é evitar o 429 a qualquer custo, é saber reagir a ele com elegância. Neste guia, vou te mostrar quais são os limites, por que a busca estoura primeiro, e como construir uma rotina que trata o 429 como parte normal da vida, não como uma emergência.

Quais são os limites de taxa

Cada portal da HubSpot tem dois tetos que importam: um limite diário, que conta o total de requisições no dia, e um limite de rajada, que conta requisições num intervalo curto, de poucos segundos. Os números variam conforme a assinatura do portal, e é importante conhecer a ordem de grandeza com que você está lidando antes de desenhar qualquer rotina pesada. A tabela abaixo traz os valores de referência atuais para aplicativos privados.

Repare que o limite de rajada é o que costuma pegar você primeiro. Um milhão de requisições por dia parece muito, mas se a sua rotina dispara duzentas chamadas num piscar de olhos, ela estoura o limite de dez segundos muito antes de chegar perto do teto diário. Por isso, o ritmo das chamadas importa tanto quanto o volume total.

Por que a busca estoura antes de tudo

Existe um detalhe que pega muita gente desprevenida: a Search API tem um limite de taxa próprio e mais restrito que as leituras simples. Ou seja, mesmo que você esteja longe do teto geral do portal, uma rotina que faz muitas buscas em sequência pode tomar 429 só por causa do limite específico da busca. Se o seu 429 aparece justamente quando a rotina está filtrando dados, e não quando está listando, a busca é a primeira suspeita. A saída costuma ser espaçar as buscas e, quando possível, trocar várias buscas pequenas por uma leitura maior seguida de filtro do seu lado, quando o volume permite.

O que fazer quando o 429 chega

A resposta 429 não vem sozinha. Ela traz um cabeçalho que indica quanto tempo esperar antes de tentar de novo. A primeira regra, e a mais importante, é respeitar esse cabeçalho. Esperar o tempo que a própria HubSpot pede é o jeito mais eficiente de voltar ao normal sem piorar a situação. A partir daí, o padrão correto é o recuo progressivo, conhecido como backoff exponencial: se a chamada falhar de novo, você espera um pouco mais antes da próxima tentativa, e vai aumentando o intervalo a cada falha consecutiva, até um teto razoável.

1. Leia o cabeçalho de retry da resposta 429 e aguarde exatamente o tempo indicado antes de tentar de novo.
2. Se por algum motivo não houver cabeçalho, comece com uma espera curta e dobre o intervalo a cada nova falha, com um limite máximo.
3. Limite a concorrência da sua rotina: menos chamadas em paralelo reduz o 429 direto na origem.
4. Para escrita em volume, use os endpoints de batch, que fazem até 100 registros por requisição, e enfileire os lotes em vez de disparar todos de uma vez.

Prevenir é melhor (e mais barato) que remediar

Tratar o 429 quando ele chega é obrigatório, mas a integração madura também trabalha para que ele apareça o mínimo possível. As alavancas que de fato reduzem o 429 mexem no número de chamadas. A primeira é preferir os endpoints de batch a chamadas individuais sempre que possível, já que uma requisição de batch resolve até cem registros de uma vez, no lugar de cem chamadas. A segunda é evitar requisições redundantes, buscando só o que você ainda não tem e reaproveitando o que já leu. A terceira é espaçar as rotinas pesadas para fora dos horários de pico de uso do portal, quando o resto da operação também está consumindo a cota. Pedir só as propriedades necessárias também ajuda, mas por outro motivo: deixa as respostas mais leves e rápidas, sem alterar o limite de taxa em si.

Monitore a taxa de 429, ela conta uma história

Um 429 isolado de vez em quando é normal e esperado. Uma taxa de 429 que sobe de forma consistente é um sinal de alerta de que a concorrência da sua rotina está alta demais, ou de que o volume cresceu além do que o desenho atual aguenta. Por isso vale a pena registrar quantos 429 a sua integração toma ao longo do tempo. Se o número vem subindo, é hora de revisar a concorrência, mover rotinas para horários mais calmos ou repensar a arquitetura, antes que o problema vire uma falha visível para o negócio.

Filas e processamento assíncrono para cargas grandes

Quando o volume é realmente alto, a melhor defesa contra o 429 não é tentar mais rápido, é desacoplar. Em vez de a sua rotina chamar a HubSpot direto, num fluxo único e síncrono, ela coloca as operações numa fila e um processador consome essa fila num ritmo controlado, respeitando o limite de rajada. Isso traz dois ganhos. Primeiro, o ritmo fica previsível e estável, porque você controla quantas operações saem por segundo, em vez de depender de quantas o seu código consegue disparar. Segundo, quando um 429 acontece mesmo assim, o item volta para a fila e é reprocessado depois, sem perder a operação e sem derrubar o restante do lote.

Esse desenho com fila é o que transforma uma integração que funciona com mil registros numa que funciona com um milhão. Ele separa a decisão de o que fazer da decisão de quando fazer, e é exatamente essa separação que dá folga para respeitar os limites sem perder trabalho. Para escrita, combine a fila com os endpoints de batch, e cada item da fila pode carregar até cem registros de uma vez.

Na prática: a carga noturna que travava no pico

Uma operação rodava uma sincronização pesada de madrugada e ela falhava de forma intermitente, sempre com 429, sem um padrão claro. A rotina disparava centenas de chamadas em paralelo para terminar mais rápido, e era justamente essa pressa que estourava o limite de rajada do portal. A correção foi contraintuitiva: desacelerar para ir mais rápido.

Ao limitar a concorrência, trocar as escritas individuais por batch e adicionar recuo progressivo no tratamento do 429, a sincronização parou de falhar e, no fim das contas, terminava em menos tempo, porque parou de bater na parede e ter que recomeçar. A lição ficou: contra os limites de taxa, ritmo constante vence disparada nervosa.

Erros comuns no tratamento do 429

Tem três armadilhas que aparecem com frequência quando uma equipe começa a tratar o 429, e todas pioram a situação em vez de resolver. A primeira é repetir a chamada imediatamente, sem nenhuma espera, na esperança de que dessa vez passe. Isso só adiciona pressão exatamente quando o portal está pedindo calma, e costuma transformar um 429 isolado numa enxurrada de 429 em cascata. A segunda é usar uma espera fixa e curta para todos os casos, o que funciona com pouca carga mas desmorona quando o volume cresce, porque a espera não acompanha a intensidade do problema.

A terceira armadilha é mais sutil: ignorar o cabeçalho de retry que a própria HubSpot envia e inventar um tempo de espera arbitrário. A plataforma sabe melhor do que você quando vale a pena tentar de novo, então o número que ela manda é o melhor palpite disponível. Respeitá-lo é mais eficiente do que qualquer chute. Some a isso o recuo progressivo para as falhas em sequência, e você tem um tratamento que se adapta sozinho à gravidade do momento, em vez de aplicar a mesma receita para um soluço e para uma tempestade.

Checklist de uma integração que respeita os limites

1. A rotina lê o cabeçalho de retry do 429 e espera o tempo indicado?
2. Existe recuo progressivo, dobrando o intervalo a cada falha consecutiva?
3. A concorrência está limitada, em vez de disparar tudo em paralelo?
4. As escritas usam batch de até 100, com os lotes enfileirados?
5. As leituras pedem só as propriedades necessárias?
6. As rotinas pesadas rodam fora dos horários de pico do portal?
7. Você monitora a taxa de 429 ao longo do tempo?

Perguntas frequentes

O erro 429 é culpa da minha integração?

Não necessariamente. É o controle de taxa da HubSpot avisando que você passou do limite no período. O esperado é tratar o 429 com backoff, e não evitá-lo a qualquer custo, porque ele faz parte do funcionamento normal da API.

Quanto tempo devo esperar antes de repetir?

O tempo indicado no cabeçalho de retry da própria resposta 429. Se não houver, use recuo progressivo: comece com uma espera curta e dobre o intervalo a cada falha, até um teto razoável.

Por que a busca dá 429 antes das leituras?

Porque a Search API tem um limite de taxa próprio e mais baixo que as leituras simples. Rotinas com muitas buscas em sequência atingem esse teto específico antes de qualquer outro.

Quais são os limites de taxa da HubSpot?

Variam por assinatura. Como referência para apps privados, o plano Professional gira em torno de 650.000 requisições por dia e o Enterprise em torno de 1.000.000, ambos com rajada de 190 a cada 10 segundos. Apps mais antigos têm limites menores.

Usar batch ajuda a evitar o 429?

Sim. Um endpoint de batch resolve até 100 registros em uma única requisição, o que reduz drasticamente o número de chamadas e, com isso, a pressão sobre os limites de taxa.

Devo aumentar a concorrência para terminar mais rápido?

Geralmente não. Concorrência alta estoura o limite de rajada e faz a rotina bater no 429 e recomeçar, terminando mais devagar. Ritmo constante e controlado costuma ser mais rápido no total.

Suas integrações travam com 429 em horário de pico ou em cargas grandes? Na Insight Sales construímos rotinas com backoff, filas e batch que rodam estáveis em volume. Fale com a gente e descubra como podemos ajudar.