O que é rate limit

Uma API de pagamento recebe chamadas de muitos sistemas ao mesmo tempo. O limite de requisições protege o serviço de picos, de laços de código com defeito e de varreduras. Para quem integra, ele é uma regra de convivência: saber quanto ainda pode chamar e o que fazer quando passa.

Como costuma funcionar

Um algoritmo comum é o token bucket, o balde de fichas. Cada requisição gasta uma ficha. O balde é reabastecido a uma taxa fixa e tem um tamanho máximo, que define quanto pico ele absorve. Quando as fichas acabam, a resposta é 429.

O Banco Central usa esse modelo no Pix. A especificação da API do DICT (versão 2.12.1) aplica políticas de limitação com token bucket, cada uma com taxa de reposição e tamanho de balde. A política de criação e remoção de vínculos, por exemplo, repõe 1.200 fichas por minuto, com balde de 36.000. Quando as fichas chegam a zero, o DICT responde com status 429.

Na API da xFlow

• O limite é por conta.
• Toda resposta autenticada traz os headers x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset. O último traz o momento da renovação como timestamp Unix (epoch, segundos).
• Acima do limite, a resposta é 429 rate_limited, e o header retry-after diz quantos segundos esperar.
• A documentação recomenda tentar de novo com backoff e monitorar os headers para não chegar ao 429.

O 429 é um dos poucos erros 4xx que vale repetir. Os outros estão em status HTTP e na tabela de erros da API Pix.

Exemplo

async function chamar(url, opcoes, tentativa = 0) {
  const res = await fetch(url, opcoes);
  if (res.status !== 429 || tentativa >= 4) return res;
  const segundos = Number(res.headers.get("retry-after") ?? 1);
  await new Promise((ok) => setTimeout(ok, segundos * 1000 * 2 ** tentativa));
  return chamar(url, opcoes, tentativa + 1);
}

A função espera o tempo do retry-after e dobra a espera a cada nova tentativa, até quatro. Em POST de cobrança ou de saque, mantenha a mesma Idempotency-Key em todas as tentativas: se uma delas tiver sido processada, a API devolve o mesmo recurso. Veja idempotência.

Termos relacionados

• Status HTTP: onde o 429 se encaixa entre os códigos de resposta.
• Idempotência: o que torna seguro repetir um pedido.
• API REST: o modelo de requisições que o limite controla.

Conteúdo informativo, atualizado em 25/10/2026. Não substitui orientação jurídica.