Como Resolver o Erro ‘API Rate Limit Exceeded’ do Notion

Você vê uma faixa vermelha ou uma resposta JSON com a mensagem “API Rate Limit Exceeded” ao usar integrações do Notion, fluxos automatizados ou scripts personalizados. Esse erro ocorre quando seu workspace ou integração envia muitas requisições à API em um curto intervalo de tempo. O Notion impõe limites de taxa para proteger a estabilidade do servidor e garantir acesso justo a todos os usuários. Este artigo explica a causa exata do erro, mostra como verificar seu uso atual e fornece correções passo a passo para reduzir a frequência de requisições e evitar o limite.

Por que o Notion Retorna o Erro API Rate Limit Exceeded

A API do Notion impõe um limite de taxa padrão de 3 requisições por segundo (RPS) para a maioria dos endpoints, com uma tolerância de rajada de até 5 RPS por curtos períodos. Quando uma integração ou script excede esse limite, a API retorna o código de status HTTP 429 com a mensagem “API Rate Limit Exceeded.” O limite se aplica por token de integração, não por workspace. Se você tiver várias integrações usando o mesmo token, suas requisições combinadas contam para o limite. O limite de taxa é redefinido após uma janela contínua de um segundo, o que significa que uma única rajada de 6 requisições em um segundo bloqueará novas requisições durante aquele segundo.

Limites de Taxa por Plano

O Notion ajusta o limite de taxa com base no plano do seu workspace. Os planos Gratuito e Plus compartilham o limite padrão de 3 RPS. Os planos Business e Enterprise recebem um limite maior de 5 RPS. O Notion não publica durações exatas de rajada ou limites por minuto, mas testes internos mostram que tráfego sustentado acima de 3 RPS por mais de 5 segundos aciona a resposta 429. A mensagem de erro inclui um cabeçalho Retry-After em segundos, que informa quanto tempo esperar antes de tentar novamente.

Gatilhos Comuns para Erros de Limite de Taxa

O erro aparece com mais frequência em três cenários. Primeiro, um script personalizado percorre um grande banco de dados e chama a API para cada página sem qualquer atraso. Segundo, uma ferramenta de automação de terceiros como Zapier ou Make envia vários webhooks em rápida sucessão. Terceiro, uma operação de importação ou exportação em massa envia muitas requisições de escrita de uma só vez. Em cada caso, a integração excede o limite de 3 RPS e recebe o erro 429.

Passos para Diagnosticar e Corrigir o Erro de Limite de Taxa

Os passos a seguir ajudam a identificar a origem das requisições excessivas e implementar controles para permanecer dentro do limite. Execute-os em ordem.

1. Verifique o Cabeçalho Retry-After na Resposta de Erro
   Ao receber o erro 429, examine os cabeçalhos da resposta HTTP. O valor Retry-After informa o número de segundos a esperar antes de enviar a próxima requisição. Por exemplo, se Retry-After for 2, pause todas as requisições por 2 segundos. Não tente novamente imediatamente sem esperar, pois isso continuará acionando o erro.
2. Veja o Painel de Uso da Sua Integração
   Acesse notion.so/my-integrations e selecione o token de integração que está atingindo o limite. O painel mostra um gráfico de requisições por segundo nas últimas 24 horas. Procure picos acima de 3 RPS. Se você vir um padrão consistente de tráfego alto, precisa reduzir a taxa de requisições.
3. Adicione um Atraso Fixo Entre Requisições Consecutivas
   Em seu script ou ferramenta de automação, insira um comando sleep(1000) (1000 milissegundos) entre cada chamada à API. Isso garante que você nunca exceda 1 requisição por segundo, bem abaixo do limite de 3 RPS. Para Python, use time.sleep(1). Para JavaScript, use setTimeout ou await new Promise(r => setTimeout(r, 1000)). Para Zapier, use a ação Delay configurada para 1 segundo.
4. Use Endpoints em Lote para Reduzir o Número de Requisições
   Em vez de buscar ou atualizar páginas uma a uma, use os endpoints em lote do Notion quando disponíveis. O endpoint Query a Database retorna até 100 páginas por requisição. Use o parâmetro start_cursor para paginar pelos resultados. Para atualizações, use o endpoint Update Page Properties com uma lista de IDs de página em uma única requisição. Isso reduz o número total de chamadas à API.
5. Implemente Backoff Exponencial para Tentativas
   Se sua integração ainda receber erros 429 ocasionais, implemente backoff exponencial. Após uma resposta 429, espere 1 segundo e tente novamente. Se falhar novamente, espere 2 segundos, depois 4 segundos, e assim por diante, até um máximo de 60 segundos. Isso evita que suas tentativas agravem o problema de limite de taxa.
6. Atualize Seu Plano do Workspace para um Limite Maior
   Se seu fluxo de trabalho realmente exigir mais de 3 RPS, considere atualizar para um plano Business ou Enterprise. Esses planos oferecem um limite de 5 RPS. Observe que o Notion não oferece aumentos de limite de taxa por integração para planos Gratuito ou Plus. Entre em contato com o suporte do Notion se precisar de um limite de taxa personalizado para uma integração empresarial.

Se o Notion Ainda Mostrar o Erro de Limite de Taxa Após as Correções

Mesmo após aplicar atrasos e operações em lote, alguns usuários continuam vendo o erro 429. As subseções a seguir abordam cenários persistentes específicos.

Múltiplas Integrações Usando o Mesmo Token

Se você tiver mais de um script ou automação usando o mesmo token de integração interna, suas requisições combinadas contam para o limite. Crie uma integração interna separada para cada fluxo de trabalho distinto. Acesse notion.so/my-integrations, clique em New Integration e gere um novo token. Atualize cada script para usar seu próprio token. Em seguida, adicione atrasos independentemente para cada fluxo de trabalho.

Enxurrada de Webhooks do Zapier ou Make

Gatilhos do Zapier ou Make que disparam a cada alteração no banco de dados podem enviar muitas requisições em pouco tempo. No Zapier, adicione uma etapa Delay configurada para 2 segundos entre o gatilho e a ação do Notion. No Make, use o módulo Sleep configurado para 1000 milissegundos. Além disso, filtre seu gatilho para disparar apenas quando condições específicas forem atendidas, como uma mudança de status, em vez de a cada edição.

Scripts de Importação em Massa que Loop Sem Pausa

Um script que importa centenas de páginas geralmente envia requisições o mais rápido possível. Modifique o script para agrupar escritas em lotes de 10 páginas e, em seguida, espere 3 segundos entre os lotes. Por exemplo, em Python, use for batch in chunks(pages, 10): e time.sleep(3) após cada lote. Isso mantém a taxa de requisições abaixo de 3 RPS mesmo durante grandes importações.

Limites de Taxa da API do Notion por Plano: Gratuito vs Plus vs Business vs Enterprise

Item	Gratuito & Plus	Business & Enterprise
Requisições por segundo (RPS)	3 RPS	5 RPS
Tolerância de rajada	Até 5 RPS para rajadas curtas	Até 8 RPS para rajadas curtas
Cabeçalho Retry-After	Incluído na resposta 429	Incluído na resposta 429
Solicitação de limite personalizado	Não disponível	Entre em contato com o suporte
Painel de integrações	Disponível	Disponível

Entender esses limites ajuda a escolher o plano certo para sua carga de trabalho. Se sua integração precisar consistentemente de mais de 3 RPS, atualizar para Business ou Enterprise é o único caminho suportado. Para a maioria dos fluxos de trabalho, adicionar um atraso de 1 segundo entre as requisições mantém você dentro do limite padrão com segurança.

Agora você pode diagnosticar o erro API Rate Limit Exceeded verificando o cabeçalho Retry-After e o painel de integrações. Adicione um atraso de 1000 ms entre as requisições e use endpoints em lote para reduzir o volume total de chamadas. Para problemas persistentes, crie tokens de integração separados por fluxo de trabalho ou atualize seu plano. Como dica avançada, use o endpoint Query a Database do Notion com um filtro para recuperar apenas páginas alteradas, o que reduz requisições desnecessárias e mantém sua integração eficiente.