Rate Limit

A API pública da Jump aplica limite de requisições (rate limit) para proteger a plataforma, garantir isolamento entre clientes e preservar a qualidade do serviço.

Como o rate limit funciona

• O controle utiliza uma janela deslizante de 1 minuto.
• Quando o limite é excedido, a API responde com 429 Too Many Attempts e novas requisições só são aceitas após o tempo indicado em Retry-After.
• O limite efetivo depende do tipo de endpoint consumido (API pública por token ou API autenticada por sessão).

Limites aplicados

API pública (Bearer Token)

Os endpoints da API pública — aqueles reconhecidos como rota pública pelo matcher interno (App\Support\PublicApiRouteMatcher), como /api/{userId}/establishment/{establishmentId}/clients, /api/{userId}/business/{uuid}/integrations/..., exportações e relatórios financeiros — utilizam um limite dedicado por token:

Limite	Janela	Escopo
120 requisições	1 minuto	Por api_key (Bearer Token enviado no header Authorization).

Observações importantes:

• O contador é atrelado ao token, não ao IP. Aplicações que compartilham o mesmo token somam consumo no mesmo contador.
• Tokens distintos possuem contadores independentes.
• Tokens inválidos ou ausentes são agrupados em um contador separado baseado no hash do valor enviado, para evitar abuso antes da validação.

API autenticada (sessão)

Os demais endpoints — utilizados pelo painel e por integrações autenticadas por sessão — seguem os limites padrão do middleware de throttle:

Contexto	Limite	Janela
Padrão	30 requisições	1 minuto
Endpoints pesados (caminhos que contêm export, resume ou extract)	20 requisições	1 minuto

Nesses casos, o escopo é uma combinação da URL chamada com o IP de origem da requisição.

Exceções

Alguns endpoints não aplicam o limite padrão do middleware:

• financial/cashflow/by
• users/login e user/login

Esses endpoints seguem regras próprias (como o limiter cashflow) ou estão isentos por natureza (como o login).

Cabeçalhos de resposta

Toda resposta de endpoint sujeito a rate limit inclui cabeçalhos que permitem monitorar o consumo da janela atual:

Cabeçalho	Quando é enviado	Descrição
X-RateLimit-Limit	Sempre	Número máximo de requisições permitidas na janela.
X-RateLimit-Remaining	Sempre	Requisições restantes na janela atual.
Retry-After	Ao atingir o limite	Segundos até a próxima requisição permitida.
X-RateLimit-Reset	Ao atingir o limite	Timestamp Unix que indica quando o contador será reiniciado.

Exemplo de resposta dentro do limite

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
Content-Type: application/json

Exemplo de resposta com limite excedido

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 37
X-RateLimit-Reset: 1714060000
Content-Type: application/json

Erros

429 Too Many Attempts

Indica que o limite de requisições foi excedido. Aguarde o tempo indicado em Retry-After (em segundos) antes de tentar novamente.

Boas práticas

• Monitore X-RateLimit-Remaining e aplique backoff antes de atingir o limite.
• Em caso de 429, respeite sempre o valor de Retry-After em vez de repetir imediatamente.
• Distribua o consumo ao longo do minuto em vez de enviar rajadas curtas concentradas.
• Ao percorrer coleções grandes com Paginação, intercale chamadas ou adicione pequenas pausas para não esgotar a janela.
• Mantenha o token (Bearer) protegido: o limite é atribuído ao token, e um vazamento pode comprometer sua aplicação mesmo sem uso indevido por parte dela.