Como Reduzir os Limites de Taxa da API do Notion com Agrupamento de Requisições

Se você cria integrações com a API do Notion, provavelmente já encontrou o erro 429 Too Many Requests. Esse erro ocorre quando sua aplicação excede o limite de taxa de 3 requisições por segundo por integração. A causa raiz é enviar chamadas individuais muito rapidamente sem coordenação. Este artigo explica como usar o agrupamento de requisições para agrupar múltiplas operações em menos chamadas, permanecendo dentro dos limites e mantendo sua integração funcionando sem problemas.

Por que os Limites de Taxa da API do Notion Afetam Sua Integração

O Notion impõe um limite de taxa de 3 requisições por segundo por token de integração. Esse limite se aplica a todos os endpoints, incluindo consulta a bancos de dados, leitura de páginas e anexação de blocos. Quando sua integração envia requisições mais rápido que 3 por segundo, a API retorna um código de status HTTP 429 com um cabeçalho Retry-After. A integração deve aguardar o número especificado de segundos antes de fazer outra requisição. Se não aguardar, o Notion pode bloquear temporariamente a integração por um minuto.

A causa mais comum de atingir esse limite é enviar uma chamada de API por linha do banco de dados ou por bloco. Por exemplo, um script que lê 100 linhas de um banco de dados chamando Retrieve a page 100 vezes em um loop excederá o limite nas primeiras 3 chamadas. Da mesma forma, anexar 10 blocos a uma página chamando Append block children 10 vezes desperdiça 9 dessas 10 chamadas. O agrupamento de requisições resolve isso combinando múltiplas operações em uma única requisição HTTP.

Métodos para Agrupar Requisições e Permanecer Dentro dos Limites

Existem duas abordagens principais para reduzir o número de chamadas de API que sua integração faz. A primeira é usar os endpoints da API do Notion que aceitam múltiplos itens em uma única requisição. A segunda é implementar um sistema de fila que espaça as requisições individuais para que nunca excedam 3 por segundo.

Use o Endpoint Append Block Children com Múltiplos Blocos

O endpoint Append block children aceita um array de objetos de bloco no parâmetro children. Em vez de enviar uma requisição por bloco, você pode enviar todos os blocos em uma única requisição. Esta é a técnica de agrupamento mais eficaz para escrever conteúdo em uma página.

1. Prepare o array de blocos
   Construa um array JSON contendo todos os objetos de bloco que deseja anexar. Cada objeto de bloco deve ter um tipo e o conteúdo correspondente do bloco.
2. Envie uma única requisição POST
   Faça POST para /v1/blocks/{block_id}/children com o array no campo children. Não envie uma requisição por bloco.
3. Verifique a resposta em busca de erros
   A API retorna um objeto com os blocos anexados. Se algum bloco falhar na validação, toda a requisição falha. Valide todos os blocos antes de enviar.

Este método reduz 10 requisições separadas para 1 requisição. Funciona para até 100 blocos por requisição. Para cargas maiores, divida os blocos em lotes de 100.

Implemente uma Fila de Requisições com Backoff Exponencial

Quando você não pode agrupar operações em uma única chamada de endpoint, use uma fila que espaça as requisições em intervalos de 333 milissegundos. Isso garante que você nunca exceda 3 requisições por segundo. Combine isso com lógica de repetição que respeite o cabeçalho Retry-After.

1. Crie um objeto de fila
   Armazene requisições pendentes em um array FIFO. Cada item da fila contém o método, URL, cabeçalhos e corpo da requisição.
2. Processe uma requisição a cada 333 milissegundos
   Use um timer ou função de atraso que aguarde 333 ms entre o processamento de cada item da fila. Isso mantém a taxa em 3 requisições por segundo.
3. Lide com respostas 429 com repetição
   Se a API retornar 429, leia o valor do cabeçalho Retry-After em segundos. Pause a fila por essa duração mais 1 segundo. Em seguida, repita a requisição com falha.
4. Registre os acionamentos do limite de taxa
   Registre cada resposta 429 com um timestamp. Se você vir múltiplos 429s, reduza o intervalo de processamento para 400 ms ou mais.

Uma fila com backoff exponencial se adapta à carga do servidor sem intervenção manual. Ela impede rajadas de requisições que disparam o erro 429.

Se os Limites de Taxa da API do Notion Ainda Bloquearem Sua Integração

Integração Bloqueada por Um Minuto Após um 429

Quando sua integração recebe uma resposta 429 e não aguarda toda a duração do Retry-After, o Notion bloqueia todas as requisições subsequentes por 60 segundos. Para corrigir isso, implemente uma lógica de repetição rigorosa que pause todas as requisições pelo valor do Retry-After mais 2 segundos. Não processe nenhum item da fila durante esse período de espera.

Consulta ao Banco de Dados Retorna Resultados Incompletos

O endpoint Query a database suporta paginação com um parâmetro page_size de até 100. Em vez de chamar Query para cada página de resultados, defina page_size como 100 e use o next_cursor para buscar as linhas restantes. Isso reduz o número de chamadas de N páginas para N dividido por 100.

Requisição em Lote Falha Devido a um Bloco Inválido

Quando você envia múltiplos blocos em uma única requisição Append block children, toda a requisição falha se mesmo um bloco for inválido. Valide cada objeto de bloco antes de adicioná-lo ao array. Verifique se campos obrigatórios como type, text content e URL estão presentes e formatados corretamente. Use a referência da API do Notion para confirmar o esquema exato para cada tipo de bloco.

Padrões de Requisição da API do Notion: Lote vs. Requisição Única

Item	Requisição em Lote	Requisição Única
Endpoint usado	Append block children com array	Append block children um bloco por chamada
Requisições para 100 blocos	1 requisição	100 requisições
Tempo para concluir	~350 ms	~33 segundos (com atraso de 333 ms entre chamadas)
Risco de limite de taxa	Baixo — permanece abaixo de 3 req/s	Alto — excede o limite no primeiro segundo
Tratamento de erros	Todo o lote falha se um bloco for inválido	Apenas o bloco com falha falha

O agrupamento de requisições é o método mais eficaz para reduzir chamadas de API e evitar limites de taxa. Use-o para todas as operações de escrita que envolvam múltiplos blocos ou linhas de banco de dados.

Agora você pode reduzir os acionamentos do limite de taxa da API do Notion agrupando anexações de blocos e implementando uma fila de requisições com backoff exponencial. Comece convertendo qualquer loop que chame Append block children em uma única requisição com um array de blocos. Para consultas de banco de dados, defina page_size como 100 e use next_cursor. Uma dica avançada: use o endpoint Retrieve a database para buscar todo o esquema uma vez e armazená-lo em cache localmente, eliminando leituras repetidas de esquema que contam contra seu limite de taxa.