Limites de uso

A Malvo aplica limites de requisição por IP, por minuto, contados de forma independente por grupo de endpoints. Eles são distintos das cotas mensais do Open Finance Brasil e dos limites da infraestrutura internacional.

Limites por IP por minuto

Grupo de endpoints	Limite (req/min)
`POST /auth`	360
`GET /transactions`, `GET /transactions/{id}`	360
`GET /investments`, `GET /investments/{id}`	360
`GET /investments/{id}/transactions`	360
`PATCH /items/{id}`	20
Todos os demais endpoints (padrão)	360

PATCH /items/{id} tem o menor limite da API: 20 req/min por IP. Ele é apenas para refreshes disparados pelo usuário. Atualizações em massa devem passar pelo auto-sync, nunca por martelar o endpoint — o excesso vira 429 ou ITEM_CREATION_LIMIT_EXCEEDED.

Resposta `429`

Quando o limite é excedido, a API responde 429 com três headers e o envelope TOO_MANY_REQUESTS.

Header	Valor
`RateLimit-Limit`	Máximo de requisições por minuto deste grupo (ex.: `360`)
`RateLimit-Reset`	Segundos até o contador zerar
`Retry-After`	Sempre `60` (padrão HTTP)

Corpo 429

{
  "code": 429,
  "message": "Too many requests. Please try again later (see Retry-After header in seconds)",
  "codeDescription": "TOO_MANY_REQUESTS"
}

Estratégia de retry

Respeite os headers no 429

Aguarde RateLimit-Reset segundos (ou Retry-After) antes de repetir. Clientes HTTP como o got honram o Retry-After automaticamente.

Backoff exponencial com jitter

No 429 e no 500, repita com backoff exponencial somando jitter (aleatoriedade) para não sincronizar várias retentativas no mesmo instante.

Refaça /auth no 401

Um 401 significa que o apiKey expirou (TTL de ~2h). Refaça POST /auth uma vez com clientId/clientSecret e repita a chamada. Num 403 vindo do /connect_token, atualize o apiKey da mesma forma.

Reduza o paralelismo

Espalhe as chamadas para ficar abaixo do limite e agende updates em lote fora do horário de pico.

Node — retry com backoff e jitter

async function withRetry(fn, { max = 5 } = {}) {
  for (let attempt = 0; attempt < max; attempt++) {
    const res = await fn();

    if (res.status === 429 || res.status >= 500) {
      const retryAfter = Number(res.headers.get("retry-after")) || 60;
      const base = Math.min(retryAfter, 2 ** attempt);
      const jitter = Math.random() * base; // jitter para dessincronizar
      await new Promise((r) => setTimeout(r, (base + jitter) * 1000));
      continue;
    }
    return res;
  }
  throw new Error("Esgotadas as tentativas após repetidos 429/5xx");
}

Não confunda 429 (limite por IP da API) com o aviso 423 no statusDetail de um Item brasileiro: o 423 sinaliza uma cota mensal do Open Finance Brasil. No Open Banking internacional, a Malvo respeita o Retry-After e o backoff do ASPSP sem transformar essa regra em uma cota mensal brasileira.

Diferente dos limites mensais do Open Finance Brasil

Os limites acima são da API da Malvo (por IP, por minuto). O Open Finance Brasil impõe limites mensais, contados por (CPF/CNPJ + instituição + produto), totalmente independentes. Quando um desses limites é atingido, a execução do Item termina em PARTIAL_SUCCESS e o produto afetado recebe o aviso de código 423 em statusDetail.<produto>.warnings[] — o produto bloqueado volta sozinho no mês seguinte. Para não esgotar a cota mensal, não crie vários Items para o mesmo CPF/instituição e prefira POST /items/{id}/refresh a criar um Item novo. Dados como saldo, cadastros e histórico completo mantêm uma cadência própria. Já no refresh manual, a janela corrente de transações (aproximadamente os últimos 7 dias) é sempre avaliada e chega ao provedor imediatamente enquanto houver capacidade no balde diário da rota e do recurso — independentemente do auto-sync. Não existe espaçamento entre as chamadas permitidas: se a capacidade for 10×/dia, as primeiras 10 podem ser consecutivas e somente a 11ª fica bloqueada até a virada do dia brasileiro. Auto-sync e refresh manual compartilham esse contador porque ambos consomem a mesma cota do Open Finance. Os detalhes e a tabela de limites mensais ficam em:

Consentimentos

Ciclo de vida do consentimento e as cotas mensais da rede de Open Finance.

Limites do Open Finance

A tabela completa de limites mensais por produto e subrecurso.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Limites de uso

Limites por IP por minuto

Resposta `429`

Estratégia de retry

Diferente dos limites mensais do Open Finance Brasil

Consentimentos

Limites do Open Finance

​Limites por IP por minuto

​Resposta 429

​Estratégia de retry

​Diferente dos limites mensais do Open Finance Brasil

Consentimentos

Limites do Open Finance

Limites por IP por minuto

Resposta `429`

Estratégia de retry

Diferente dos limites mensais do Open Finance Brasil