# Operational Rate Limits

## Open Finance Rate Limits

There are two different kinds of limits involved when Pluggy retrieves data: Pluggy API rate limits and Open Finance operational limits imposed by financial institutions.

The Brazilian Open Finance Network imposes **operational limits** on the number of times **per month** that anyone using Open Finance can fetch each **product**. These limits do not come from Pluggy; they constrain how often Pluggy can synchronize data. They apply per combination of CPF/CNPJ, institution, and product (i.e., card, account, investment, or loan).

> **Pluggy manages rate limits, so you don't have to worry about it.**
>
> Under normal usage of Open Finance Connectors (one CPF and institution **on only one item**), you **won't have to worry about Rate Limits**, since you would never reach them even if you had automatic updates enabled on all your items updating up to 4 times per day.

> **Creating multiple items for the same CPF/CNPJ + Institution**
>
> However, keep in mind that if you connect the same CPF/CNPJ to the same institution by creating multiple items, you will reach the limitation of Open Finance faster, meaning that some products won't be updating/returning their data until the limit is renewed on the next month. When not using an item, **trigger the deletion** of it to avoid syncing automatically.

### Accounts (Checking and Savings)

| Product | Monthly requests allowed | Moments we fetch this product |
| --- | --- | --- |
| Account list & details | 4 | Item creation and every 7 days |
| Account balance | 420 | Every update * |
| Recent transactions (1 to 6 days ago) | 240 | Every update * |
| Non-recent transactions (7 to 365 days ago) | 4 | Item creation and every 7 days |

\* Every Update means that each execution the item does.

**Considerations**

- After 240 requests, new transactions won't appear until the next month.
- After 420 requests, the account's balance won't be updated until the next month.
- On every update, both requests are consumed, and currently, it's not supported to just recover the balance. If needed, create a connection that would only recover the **ACCOUNTS** product, sending in the `products` array the desired product.

### Credit Cards

| Product | Monthly requests allowed | Moments we fetch this product |
| --- | --- | --- |
| Credit card list & details | 4 | Item creation and every 7 days |
| Credit card bills & bill transactions | 30 | Item creation and once per day |
| Credit card limits | 240 | Every update * |
| Recent transactions (1 to 6 days ago) | 240 | Every update * |
| Non-recent transactions (7 to 365 days ago) | 4 | Item creation and every 7 days |

\* Every Update means that each execution the item does.

**Considerations**

- If a new credit card appeared as authorized, it could take up to 7 days to appear in the responses.
- Credit card bill transactions (closed and past bills) will be updated daily.
- Credit card limits and new transactions will be synced on every update.
  - After 240 updates, this has an average of 8 updates per day. It will hit the rate limits and won't update transactions until the next month.

### Investments

| Product | Monthly requests allowed | Moments we fetch this product |
| --- | --- | --- |
| Investment list | 30 | Item creation and once per day |
| Investment detail | 4 | Item creation and every 7 days |
| Investment balance | 120 | Every update * |
| Investment Transactions (Recent - 1 to 6 days ago) | 120 | Every update * |
| Investment Transactions (History - 7 to 365 days ago) | 4 | Item creation and on demand. |

\* Every Update means that each execution the item does.

**Considerations**

- If an item it's updated 120 times before the end of the month, new transactions nor balances won't be synced until the 1st of the next month.
- Details recover the asset's rate, rateType, fixedAnnualRate, etc. This information shouldn't change, and it's recovered on creation. If there is a change for some reason, it will be reflected after 7 days from that update.
- If a new investment was acquired, but the rate limit was already achieved, it won't appear until the next month.

### Other products

| Product | Monthly requests allowed | Moments we fetch this product |
| --- | --- | --- |
| Identity | 4 | Item creation and every 7 days |
| Loans List & Detail | 4 | Item creation and every 7 days |
| Loans Instalments | 30 | Item creation and once per day |
| Loans Payments | 30 | Item creation and once per day |

- Loans will be updated daily, if an item is updated more than once per day, it won't sync loan's data.
- Identity information is recovered on item creation and will sync updates every 7 days. If there is any personal data updated, won't reflect changes until it executes a sync after 7 days from the initial sync.

## Understanding an item that reached the rate limit

### How is the rate limit returned as a warning?

When a rate limit is reached, you will see the Item in status **PARTIAL_SUCCESS** and inside the status detail, a warning about the failing product:

```json
{
  "id": "44534b0e-717e-497d-890f-08c2faa468c1",
  "status": "PARTIAL_SUCCESS",
  "statusDetail": {
    "accounts": {
      "warnings": [
        {
          "code": "423",
          "message": "Open Finance monthly rate limit reached on product 'accounts' for this CPF/CNPJ and institution. The product could not be updated."
        }
      ],
      "isUpdated": false,
      "lastUpdatedAt": "2023-10-19T19:19:58.188Z"
    }
  }
}
```

## Response time and timeout

Monthly operational limits are not the only non-functional requirement the Brazilian Open Finance Network imposes on institutions. Two others matter when a sync fails because the institution was slow to answer, and they are frequently confused with each other:

| Requirement | Limit | What it measures |
| --- | --- | --- |
| **Timeout** | **15 seconds** | How long the client waits for a single request before giving up. The institution is expected to answer `504 Gateway Timeout` when it hits its own timeout. |
| **Performance** | P95 under **1,500 ms** (high and medium-high frequency endpoints), **2,000 ms** (medium frequency), **4,000 ms** (low frequency) | The 95th percentile of the institution's response time, measured across its full daily traffic on that endpoint. |

Pluggy applies the network's **15-second timeout to every Open Finance request to the institution, on every connector** — there is no per-institution or per-product value. When an institution does not answer within that window, we abort the request; the affected product is not updated and a warning is added to the Item's `statusDetail`, exactly as shown above for rate limits.

> **A slow response is not a timeout.**
>
> The 1,500 ms figure is a *performance* target measured over an institution's aggregate traffic — it is not a deadline for any individual request. A request answered in 1,600 ms, or in 9 seconds, is well inside the 15-second limit and Pluggy will wait for it and use the response. Only requests that go past **15 seconds** are aborted.

This distinction is worth keeping in mind when raising a case with an institution: exceeding the P95 target and exceeding the timeout are two different breaches, with different evidence behind them.