Limites de requisição

100 por minuto no geral, 20 por minuto em saque. E como não bater neles.

​

Os limites

Escopo	Limite	Janela
Todas as rotas /v1/*	100 requisições	60 segundos, por conta
POST /v1/payments	100 cobranças	60 segundos, por conta, dentro do limite acima
POST /v1/withdrawals, POST /v1/subaccounts/{id}/withdrawals e POST /v1/refunds	20 no total	60 segundos, por conta
POST e PATCH em /v1/payment-links	60	1 hora, por conta

O limite geral é somado entre todos os endpoints e todas as chaves da conta. Não existe cota separada por chave nem por recurso.

A janela é deslizante: em nenhum intervalo de 60 segundos passam mais pedidos que o limite, e o contador não zera de uma vez na virada do minuto. Cada pedido libera a vaga dele 60 segundos depois de feito.

​

Headers

Toda resposta com chave de API traz os headers padrão, então dá pra desacelerar antes de bater no teto:

Header	Conteúdo
RateLimit-Limit	Total permitido na janela
RateLimit-Remaining	Quanto ainda resta
RateLimit-Reset	Segundos até liberar a próxima vaga

​

Quando estoura

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 42

{ "error": { "code": "RATE_LIMITED", "message": "Muitas tentativas. Espere um pouco e tente de novo." } }

Não faça retry imediato de um 429. Você continua recusado até liberar uma vaga, e repetir em laço só gasta tempo do seu servidor.

Espere pelo menos o Retry-After (ele vale também nos limites de saque e de cobrança), e use backoff exponencial com jitter:

async function comRetry(fn, maxTentativas = 5) {
  for (let i = 0; i <= maxTentativas; i++) {
    const res = await fn();
    if (res.status !== 429) return res;

    const espera = Number(res.headers.get("Retry-After")) || 2 ** i;
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, espera * 1000 + jitter));
  }
  throw new Error("rate limit: máximo de tentativas excedido");
}

O jitter não é enfeite: sem ele, todos os seus workers acordam no mesmo instante e batem no limite de novo, juntos. Ao repetir um POST de cobrança ou saque, mande a mesma Idempotency-Key: assim o retry nunca cria nada em dobro (Convenções).

​

O jeito de não chegar perto

​

Use webhook em vez de polling

É de longe a maior economia. Um Pix consultado a cada 3 segundos durante os 30 minutos de validade são 600 requisições. O webhook payment.paid resolve em uma.

​

Se precisar consultar, espace

Intervalo de 5 segundos ou mais, e pare no primeiro status final (paid, expired ou refunded).

​

Pagine com limite alto

As listagens aceitam limit até 100 e paginam por cursor. Buscar de 10 em 10 gasta 10 vezes mais requisição pelo mesmo resultado.

​

Cacheie o que não muda

As formas de pagamento (GET /v1/payments/methods) e as tarifas da conta (GET /v1/fees) mudam pouco: leia uma vez e guarde por alguns minutos, em vez de consultar a cada pedido do seu cliente. O saldo, consulte quando for usar.

Se você tem vários serviços integrando, dê uma chave para cada um. O limite é da conta, somado entre as chaves, mas assim você vê em Integrações e API qual chave foi usada por último e pode desligar só a do serviço que está gastando requisição à toa.