# Limites Operacionais de Taxa

## Limites de Taxa do Open Finance

Existem dois tipos diferentes de limites envolvidos quando a Pluggy recupera dados: limites de taxa da API da Pluggy e limites operacionais do Open Finance impostos pelas instituições financeiras.

A Rede Brasileira de Open Finance impõe **limites operacionais** sobre o número de vezes **por mês** que qualquer pessoa usando Open Finance pode buscar cada **produto**. Esses limites não vêm da Pluggy; eles restringem com que frequência a Pluggy pode sincronizar dados. Eles se aplicam por combinação de CPF/CNPJ, instituição e produto (ou seja, cartão, conta, investimento ou empréstimo).

> **A Pluggy gerencia os limites de taxa, para que você não precise se preocupar com isso.**
>
> Sob o uso normal dos Conectores do Open Finance (um CPF e instituição **em apenas um item**), você **não precisará se preocupar com Limites de Taxa**, já que você nunca os alcançaria mesmo que tivesse atualizações automáticas habilitadas em todos os seus itens, atualizando até 4 vezes por dia.

> **Criando múltiplos itens para o mesmo CPF/CNPJ + Instituição**
>
> No entanto, tenha em mente que se você conectar o mesmo CPF/CNPJ à mesma instituição criando múltiplos itens, você atingirá a limitação do Open Finance mais rapidamente, o que significa que alguns produtos não estarão atualizando/retornando seus dados até que o limite seja renovado no próximo mês. Quando não estiver usando um item, **inicie a exclusão** dele para evitar a sincronização automática.

### Contas (Corrente e Poupança)

| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Lista e detalhes da conta | 4 | Criação do item e a cada 7 dias |
| Saldo da conta | 420 | A cada atualização * |
| Transações recentes (1 a 6 dias atrás) | 240 | A cada atualização * |
| Transações não recentes (7 a 365 dias atrás) | 4 | Criação do item e a cada 7 dias |

\* Cada Atualização significa que cada execução que o item faz.

**Considerações**

- Após 240 solicitações, novas transações não aparecerão até o próximo mês.
- Após 420 solicitações, o saldo da conta não será atualizado até o próximo mês.
- Em cada atualização, ambas as solicitações são consumidas, e atualmente, não é suportado apenas recuperar o saldo. Se necessário, crie uma conexão que apenas recupere o produto **CONTAS**, enviando no array `products` o produto desejado.

### Cartões de Crédito

| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Lista e detalhes do cartão de crédito | 4 | Criação do item e a cada 7 dias |
| Faturas de cartão de crédito & transações de fatura | 30 | Criação do item e uma vez por dia |
| Limites de cartão de crédito | 240 | A cada atualização * |
| Transações recentes (1 a 6 dias atrás) | 240 | A cada atualização * |
| Transações não recentes (7 a 365 dias atrás) | 4 | Criação do item e a cada 7 dias |

\* Cada Atualização significa que cada execução que o item faz.

**Considerações**

- Se um novo cartão de crédito aparecer como autorizado, pode levar até 7 dias para aparecer nas respostas.
- Transações de fatura de cartão de crédito (faturas fechadas e passadas) serão atualizadas diariamente.
- Limites de cartão de crédito e novas transações serão sincronizados em cada atualização.
  - Após 240 atualizações, isso tem uma média de 8 atualizações por dia. Ele atingirá os limites de taxa e não atualizará transações até o próximo mês.

### Investimentos

| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Lista de investimentos | 30 | Criação do item e uma vez por dia |
| Detalhe do investimento | 4 | Criação do item e a cada 7 dias |
| Saldo do investimento | 120 | A cada atualização * |
| Transações de Investimento (Recentes - 1 a 6 dias atrás) | 120 | A cada atualização * |
| Transações de Investimento (Histórico - 7 a 365 dias atrás) | 4 | Criação do item e sob demanda. |

\* Cada Atualização significa que cada execução que o item faz.

**Considerações**

- Se um item for atualizado 120 vezes antes do final do mês, novas transações ou saldos não serão sincronizados até o dia 1 do próximo mês.
- Detalhes recuperam a taxa do ativo, rateType, fixedAnnualRate, etc. Essas informações não devem mudar e são recuperadas na criação. Se houver uma mudança por algum motivo, será refletida após 7 dias daquela atualização.
- Se um novo investimento foi adquirido, mas o limite de taxa já foi atingido, ele não aparecerá até o próximo mês.

### Outros produtos

| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Identidade | 4 | Criação do item e a cada 7 dias |
| Lista & Detalhe de Empréstimos | 4 | Criação do item e a cada 7 dias |
| Parcelas de Empréstimos | 30 | Criação do item e uma vez por dia |
| Pagamentos de Empréstimos | 30 | Criação do item e uma vez por dia |

- Empréstimos serão atualizados diariamente, se um item for atualizado mais de uma vez por dia, não sincronizará os dados do empréstimo.
- As informações de identidade são recuperadas na criação do item e sincronizarão atualizações a cada 7 dias. Se houver algum dado pessoal atualizado, não refletirá mudanças até que execute uma sincronização após 7 dias da sincronização inicial.

## Entendendo um item que atingiu o limite de taxa

### Como o limite de taxa é retornado como um aviso?

Quando um limite de taxa é atingido, você verá o Item no status **PARTIAL_SUCCESS** e dentro do detalhe do status, um aviso sobre o produto que falhou:

```json
{
  "id": "44534b0e-717e-497d-890f-08c2faa468c1",
  "status": "PARTIAL_SUCCESS",
  "statusDetail": {
    "accounts": {
      "warnings": [
        {
          "code": "423",
          "message": "Limite mensal de taxa do Open Finance atingido no produto 'accounts' para este CPF/CNPJ e instituição. O produto não pôde ser atualizado."
        }
      ],
      "isUpdated": false,
      "lastUpdatedAt": "2023-10-19T19:19:58.188Z"
    }
  }
}
```

## Tempo de resposta e timeout

Os limites operacionais mensais não são o único requisito não funcional que a Rede Brasileira de Open Finance impõe às instituições. Outros dois são importantes quando uma sincronização falha porque a instituição foi lenta para responder, e eles são frequentemente confundidos entre si:

| Requisito | Limite | O que mede |
| --- | --- | --- |
| **Timeout** | **15 segundos** | Quanto tempo o cliente espera por uma única solicitação antes de desistir. Espera-se que a instituição responda `504 Gateway Timeout` quando atinge seu próprio timeout. |
| **Desempenho** | P95 abaixo de **1.500 ms** (endpoints de alta e média-alta frequência), **2.000 ms** (média frequência), **4.000 ms** (baixa frequência) | O percentil 95 do tempo de resposta da instituição, medido em todo o seu tráfego diário naquele endpoint. |

A Pluggy aplica o **timeout de 15 segundos** da rede a cada solicitação de Open Finance à instituição, em cada conector — não há valor por instituição ou por produto. Quando uma instituição não responde dentro desse intervalo, abortamos a solicitação; o produto afetado não é atualizado e um aviso é adicionado ao `statusDetail` do Item, exatamente como mostrado acima para limites de taxa.

> **Uma resposta lenta não é um timeout.**
>
> O valor de 1.500 ms é uma meta de *desempenho* medida sobre o tráfego agregado de uma instituição — não é um prazo para qualquer solicitação individual. Uma solicitação respondida em 1.600 ms, ou em 9 segundos, está bem dentro do limite de 15 segundos e a Pluggy aguardará por ela e usará a resposta. Apenas solicitações que ultrapassam **15 segundos** são abortadas.

Essa distinção vale a pena ter em mente ao abrir um caso com uma instituição: exceder a meta P95 e exceder o timeout são duas infrações diferentes, com evidências diferentes por trás delas.