Limites de Requisicao

Os limites de requisicao sao aplicados por endpoint em uma janela deslizante de 60 segundos. Cada endpoint tem seu proprio contador, entao atingir o limite em uma rota nunca afeta outra. Exceder um limite retorna 429 Too Many Requests.

Como funciona

• A janela e de 1 minuto para todos os endpoints.
• Os limites sao isolados por endpoint — list-boards e send-message sao contados separadamente.
• Toda resposta traz headers de rate limit para que voce possa se controlar antes de atingir o limite.

Headers de resposta

Header	Descricao
X-RateLimit-Limit	Maximo de requisicoes permitidas para este endpoint por janela.
X-RateLimit-Remaining	Requisicoes restantes na janela atual.
X-RateLimit-Reset	Quando a janela atual reinicia.
Retry-After	Segundos para aguardar antes de tentar novamente (enviado apenas no 429).

Limites por categoria

Os limites se agrupam em algumas faixas. O limite exato depende de quao pesada e a operacao.

Categoria	Limite tipico (por minuto)	Exemplos
Leituras	50	Listar boards, obter uma linha, listar channels, listar notificacoes, listar bookings
Leituras mais pesadas	30	Arvore de docs, arvore de drive, todas as leituras /workspace/*
Gravacoes	30	Criar/atualizar/excluir linhas, docs, comentarios, pastas; URLs presigned de upload
Gravacoes pesadas	20	Gravacoes de markdown (linha, coluna, doc), inicio/finalizacao de upload multipart
Busca	60	O endpoint /search entre entidades (buscas de docs/drive sao 50)
Mutacoes de notificacao	60	Marcar como lida/nao lida, excluir
Mensagens	100	Enviar mensagem de channel, enviar mensagem direta
Export	10	Export assincrono de tabela (o endpoint mais restrito)

Limites representativos por endpoint

Endpoint	Metodo	Limite / min
/board/list-boards	GET	50
/board/{boardId}/table/{tableId}/rows	GET	50
/board/{boardId}/table/{tableId}/row	POST	30
/board/{boardId}/table/{tableId}/row/{rowId}/md	POST	20
/board/{boardId}/table/{tableId}/export	POST	10
/docs/tree	GET	30
/docs/{docId}/md	POST	20
/drive/files/upload/multipart/start	POST	20
/search	GET	60
/notifications	GET	50
/notifications/{notificationId}	PATCH / DELETE	60
/workspace/info	GET	30
/chat/channels	GET	50
/chat/channel/{channelId}/send-message	POST	100

observação

Esses numeros estao corretos no momento em que isto foi escrito, mas podem mudar. Sempre leia os headers X-RateLimit-* em tempo de execucao, em vez de fixar os limites no codigo — e consulte a Referencia da API para o valor atual de um endpoint especifico.

A resposta 429

Quando voce excede um limite, o endpoint retorna:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests, please try again later",
  "retryAfter": 27
}

O header Retry-After carrega o mesmo valor (em segundos) que o campo retryAfter do corpo — o tempo ate a janela reiniciar.

Orientacoes de backoff

• Respeite o Retry-After. Em um 429, aguarde o numero de segundos que ele especifica antes de tentar novamente.
• Use backoff exponencial como fallback. Se nenhum Retry-After estiver presente (por exemplo, em um 5xx), faca o backoff de forma exponencial: 1s, 2s, 4s, …
• Observe o X-RateLimit-Remaining. Desacelere proativamente a medida que ele se aproxima de zero, em vez de esperar por um 429.
• Distribua o trabalho em massa. Ao iterar sobre listas grandes ou criar linhas em lote, adicione um pequeno intervalo entre as chamadas para ficar abaixo do limite por minuto.
• Limite os retries. Desista apos algumas tentativas e exiba o erro, em vez de tentar para sempre.

Veja Tratamento de Erros para um exemplo completo de retry.