OFDA Brazil Data Retrieval Limits

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Introduction

Brazil's Open Finance Network sets monthly limits regarding how often you can retrieve data for a specific person or business. These operational limits are linked to a combination of:

• the user's CPF or CNPJ
• the API data you want to get (Owners, Accounts, Transactions, Bills, Balances, Investments, or Investment transactions)
• the Open Finance network certificate

Once the monthly operational limit of API calls is reached, no more information can be retrieved for the CPF/CNPJ until the start of the next calendar month. However, Belvo has implemented optimizations to maximize the amount of data you can retrieve for your users according to your data needs.

The limits are outlined in the table below:

Asynchronous workflow (single links)

Data frequency needs: Low

You only need to retrieve historical information once (or once a week). For example, credit lenders or ID verification.

When you create a single link using our asynchronous workflow (which uses our fetch_resources parameter), Belvo will asynchronously retrieve the historical information for your user (up to 365 days). After you receive the webhook notification that the historical data is available, you can retrieve it using GET calls.

For any subsequent POST calls you make after link creation, the information that you retrieve will depend on the API resource (see the table below).

Asynchronous workflow (recurrent links)

Data frequency needs: High

You need balance, overdraft, and transaction information on a daily basis. For example, PFMs or ERPs.

When you create a recurrent link, Belvo will asynchronously retrieve the historical information for your user (up to 365 days). After you receive the webhook notification that the historical data is available, you can retrieve it using GET calls as usual. Depending on your refresh rate, you will receive webhooks indicating whether a new account, owner, transaction, or bill has been retrieved from the institution, which you can also retrieve using GET calls.

Any individual POST call you make will retrieve the following information:

Single links

Data frequency needs: Very low

You only need to retrieve historical information once. For example, one-off credit analysis.

When you create a single link without historical data, you will need to make individual POST calls to retrieve data for your user.

Any subsequent individual POST call you make will retrieve the following information:

Given the limits, is it possible that account and owner data for a recurrent link will not be updated for an entire month?

Yes, in the situation where the operational limit has been reached for a CPF/CNPJ, the recurrent link will not be updated (and new accounts or owners will not be identified). This can occur for three reasons:

1. The user has created a link four times within the month.
2. Clients not using asynchronous workflows have used up the operational limits for the CPF/CNPJ using POST calls.

Do I still receive webhooks for daily or weekly refreshes?

Yes. Depending on your refresh rate, Belvo sends webhooks when new accounts, owners, transactions, or bills are retrieved from the institution. As the limits for transactional information within the last six days are larger (240 requests), you will continue to receive webhooks for new transactions. Account, owner, and bill webhooks are subject to their respective monthly limits.

What API error will I receive when the limit is reached?

When the limit is reached on a synchronous POST request, you receive a 400 HTTP error (operational_limits_reached), indicating that Belvo could not retrieve information for the link due to the limits being reached.

[
  {
    "code": "operational_limits_reached",
    "message": "The institution has reached its operational limits",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

What webhook will I receive in asynchronous flows?

In asynchronous flows (for example, when you create a link with fetch_resources or when a recurrent link is refreshed), Belvo sends a webhook when operational limits prevent retrieval for a given link and resource. The payload uses the same operational_limits_reached error code inside the data.errors array, with webhook_code and process_type set according to the workflow (commonly historical_update for the initial historical load).

The webhook_type indicates which resource could not be retrieved—for example, TRANSACTIONS, ACCOUNTS, OWNERS, INVESTMENTS, or INVESTMENT_TRANSACTIONS.

{
  "webhook_id": "4d77a0107c1d4fe9b252bf24f9b9c57c",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "74f98fe6-f460-4c3f-8a70-2768bc727f48",
  "request_id": "a47e488b4ee2437cb7757244455170f5",
  "external_id": "a0ea1b54bc2b5559e3dcc4be25163e1b87aa0d53d14201a6825dd79f576a017e_accountChange",
  "data": {
    "errors": [
      {
        "code": "operational_limits_reached",
        "message": "Operational Limit Reached"
      }
    ]
  }
}

For the full webhook schema and other error payloads, see Aggregation Webhooks.

Will my user be aware that they have reached the limit when creating their link?

As the API calls occur after the user has created their link, they will not receive any error which indicates that the application they're granting consent to won't be able to retrieve data.