A rede de Open Finance Brasil impõe limites mensais de consumo por combinação de (CPF/CNPJ + instituição + endpoint + objeto mais granular), contados por mês. Eles são independentes dos limites por IP da API — estourar a cota mensal da rede não é o mesmo que levar um 429 da API.
Esta página é exclusiva do Open Finance Brasil. No Open Banking internacional, limites e janelas variam por ASPSP; a Malvo respeita Retry-After, backoff e resultados parciais, sem aplicar a tabela mensal brasileira abaixo.
Estes limites são da rede de Open Finance, não da Malvo. Eles existem por documento + instituição + endpoint + objeto granular, por mês — o “objeto granular” é o recurso específico (cada accountId, creditCardAccountId, investmentId, billId). Não há pool compartilhado entre contas: consultar transações de 3 contas do mesmo titular consome o limite de cada uma independentemente. Os rate limits da API são por IP, por minuto. As duas coisas são separadas.

​
Tabela de limites mensais

​
O aviso 423 e o PARTIAL_SUCCESS

Quando um limite mensal é atingido:
  • A execução do Item finaliza em executionStatus: PARTIAL_SUCCESS.
  • O produto afetado recebe o aviso código 423 em statusDetail.<produto>.warnings[] (podendo aparecer ao lado de códigos como TXN_xxx / INV_xxx).
  • O produto bloqueado volta a funcionar automaticamente no mês seguinte.
Exemplo de statusDetail com o aviso 423 em transações:
Ao receber 423 / PARTIAL_SUCCESS, mostre um aviso amigável ao usuário e não faça retry agressivo — repetir só consome a cota mais rápido. O produto se restabelece sozinho no próximo mês.

​
Como não estourar a cota

A Malvo agenda e deduplica as chamadas à instituição para que um Item por (CPF/CNPJ, instituição) com auto-sync padrão permaneça dentro da cota. Para manter isso do seu lado:
  • Use apenas um Item por (CPF/CNPJ + instituição). Criar vários Items para o mesmo documento e a mesma instituição multiplica o consumo da cota.
  • Prefira atualizar a recriar. Para atualizações ad-hoc, use POST /items/{id}/refresh (ou PATCH /items/{id}) em vez de criar um novo Item — Items novos consomem cota da rede.
  • Renove o consentimento no mesmo Item. Quando um consentimento expira ou é revogado, dispare a atualização no mesmo itemId (PATCH / update mode). Nunca crie um Item novo só para renovar.
  • Confie no auto-sync para o refresh periódico, em vez de chamar PATCH /items/{id} repetidamente (esse endpoint tem o menor cap da API: 20 req/min).

​
Cadência dos dados e cota diária do refresh

Para os dados que não usam transactions-current, a Malvo mantém uma cadência por endpoint e recurso. Se um sync pedir o mesmo dado antes desse intervalo, a Malvo devolve o último valor coletado sem gastar uma nova chamada no provedor. O POST /items/{id}/refresh trata a janela corrente de transações de outra forma. A Malvo sempre avalia transactions-current — aproximadamente os últimos 7 dias — para cada conta, cartão e investimento e consulta o Open Finance imediatamente enquanto houver capacidade diária: A regra geral é limite mensal ÷ 30, mas as rotas transactions-current de conta e de cartão têm um teto fixo de 4 chamadas por dia (não as 8 derivadas): o auto-sync usa no máximo 3, sobra pelo menos um slot interativo e o orçamento mensal não pode ser queimado em um único dia de rajada. Um override explícito em CELCOIN_OF_QUOTAS dispensa o teto e recebe a fatia mensal ÷ 30 integral. Não existe intervalo entre essas chamadas. Em uma rota com capacidade de 4 chamadas no dia, as chamadas 1 a 4 podem ocorrer consecutivamente; o lock só começa na 5ª tentativa. O contador reinicia na virada do dia brasileiro e é mantido por endpoint, consentimento e recurso granular. A cota mensal absoluta e um eventual cooldown informado pela instituição continuam valendo. O autoSyncFrequency apenas agenda execuções automáticas e não reduz nem espaça a capacidade do refresh manual. Como auto-sync e refresh manual chegam ao mesmo Open Finance, uma chamada realmente feita por qualquer um deles consome o mesmo balde diário do provedor. Falhas transitórias de rede ou 5xx podem gerar até 3 tentativas no total, com 10 segundos entre elas. Cada tentativa física também consome os contadores diário e mensal. A política de retry nunca ultrapassa o saldo disponível: se a última vaga diária for consumida por uma tentativa que falhou, o lock começa imediatamente e as tentativas restantes não chegam ao provedor. Depois de três falhas da mesma rota em uma execução, os demais recursos dessa rota usam cache até a próxima execução, sem multiplicar as chamadas por todas as contas.
Quando o balde diário já estiver esgotado antes de iniciar a leitura, o refresh não chama novamente o Open Finance para aquela rota/recurso: mantém o último valor coletado, sem marcar PARTIAL_SUCCESS. Uma nova chamada é liberada automaticamente no próximo dia. Se a última vaga foi consumida por uma tentativa transitória que falhou, a falha continua registrada como parcial. O lock diário, portanto, só existe depois do consumo de toda a capacidade daquele dia.
Para saber quando um dado de fato mudou, assine os webhooks (item/updated, transactions/created|updated|deleted) em vez de refazer refresh em loop. Veja Sincronizar transações.

​
Distinção: limites da rede vs. rate limits da API

​
Relacionado

  • Limites de uso — os limites por IP por minuto e a resposta 429.
  • Consents — ciclo de vida do consentimento e renovação no mesmo Item.
  • Códigos de erro — onde o PARTIAL_SUCCESS se encaixa nos executionStatus.