# Introduction

Errors are annoying - we know. That's why we have dedicated articles for each error in our DevPortal to help you solve them. Have a look at the error below, or just search for the error code you are encountering to go straight to the causes as well as solutions.

## Response Codes

We use the following HTTP status code in the response depending on the success or failure:

| Status Code | Description |
|  --- | --- |
| `200` | ✅ **Success** - The content is available in the response body. |
| `201` | ✅ **Success** - The content was created successfully on Belvo. |
| `204` | ✅ **Success** - No content to return. |
| `400` | ❌ **Bad Request Error** - Request returned an error, detail in content. |
| `401` | ❌ **Unauthorized** - The Belvo credentials provided are not valid. |
| `403` | ❌ **Forbidden** - You don’t have the required permissions to perform this action. |
| `404` | ❌ **Not Found** - The resource you try to access cannot be found. |
| `405` | ❌ **Method Not Allowed** - The HTTP method you are using is not accepted for this resource. |
| `408` | ❌ **Request Timeout** - The request timed out and was terminated by the server. |
| `409` | ❌ **Conflict** - The request could not be completed due to a conflict with the current state of the resource. |
| `428` | ❌ **MFA Token Required** - MFA token was required by the institution to connect. |
| `500` | ❌ **Internal Server Error** - The detail of the error is available in the response body. |


Belvo API errors are returned in JSON format. For example, an error might look like this:


```json Example of a 400 Bad Request error
[
  {
    "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
    "message": "This field is required.",
    "code": "required",
    "field": "link"
  }
]
```

Typically, an error response will have the following parameters:

- `request_id`: a unique ID for the request, you should share it with the Belvo support team for investigations.
- `message`: human-readable description of the error.
- `code`: a unique code for the error. Check the table below to see how to handle each error code.
- `field` *(optional)*: The specific field in the request body that has an issue.


## General error handling notes

Here is our recommendation in terms of retry on errors:

### 50x errors

Implement an automated exponential backoff of up to five retries. We recommend that you use a base interval of three seconds with a factor of two. For example, the first retry should be after three seconds, the second retry is after 6 seconds (2*3), the third retry is after 12 seconds (2*6), the fourth retry is after 24 seconds (2*12), and the fifth retry is after 48 seconds (2*24).

### 40x errors

You should not retry making requests if you get 40x response as this is a client error.

The only exception is the “Too Many Sessions" error, as it means that your end-user is accessing the account from another browser at the same time. In this case, please implement the same retry policy as with 50x errors.

Store the request_id
When implementing your Belvo integration, make sure that you account for storing the `request_id` when you receive an error. This way, when you provide our engineers the ID, they can troubleshoot the issue quickly and get you back up and running.

## 400 activation_failed

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Institution | No* |
| Enrichment | Institution | No* |
| Payment Initiation | N/A | N/A |


* This error is not normally displayed in the widget. However, there are exceptions where it does reflect in the widget for some institutions such as BBVA in Mexico. Reach out to us at support@belvo.com if you have any questions


```json Activation Failed Example
[
  {
    "code": "activation_failed",
    "message": "The credentials provided were not accepted by the institution.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249gg"
  }
]
```

**Cause**

This error occurs when Belvo was unable to automatically activate the internet banking access for the user due to missing information (for example, the 🇲🇽 CVV or 🇲🇽 NIP were missing or incorrectly provided).

**Solution**

Ask the user to first activate their internet banking access (either by contacting the bank directly or attempting to log in to their internet banking account) and then ask them to connect their account again.

## 400 already_exists

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | N/A | N/A |
| Enrichment | N/A | N/A |
| Payment Initiation | Request | No |



```json Already Exists Example
[
    {
        "field": "details",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "pix_key": {
            "value": {
                "message": "This `pix_key__value` already exists. It is linked to BankAccount: d5c8cb5f-7845-4a23-a1fa-76c7ae7e5e36",
                "code": "already_exists"
            }
        }
    }
]
```

**Cause**

You are trying to register a bank account providing a value that is already linked to a bank account registered in Belvo. This could include:

- The PIX key identifier of the bank account
- The bank account number



```json Bank Account Error Example
{
  "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
  "holder": {
    "type": "BUSINESS",
    "information": {
        "identifier_type": "CNPJ",
        "name": "Caetano Veloso Entertainment Universe",
        "identifier": "231.002.990-00"
          }
     },
   "details": {
        "country": "BRA",
        "account_type": "CHECKINGS",
        "agency": "0444",
        "number": "45722-01" // Account number already registred in Belvo.
     }
}
```

**Solution**

Make a Get all bank accounts request to receive a list of all the bank accounts you have registered, filtering the results by the last four bank account digits to get the details.

## 400 blank

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |
| Payment Initiation | Request | No |



```json Blank Error Example
[
    {
        "field": "institution",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "This field may not be blank.",
        "code": "null"
    }
]
```

**Cause**

You sent a request with an empty string for a required field. For example:


```json Blank Field Request Example
{
    "institution": "", // This field is required and cannot be an empty string.
    "username": "bnk100",
    "password": "full",
}
```

**Solution**

- Check the error message to see which field you need to provide. If you're not sure what information to provide or the format, just check our API reference documentation.


## 400 cancellation_error

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Payment Initiation | Request | No |


Payment Intent Not Scheduled Error Example

```json
[
    {
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "Payment Intent cannot be canceled because it is not SCHEDULED",
        "code": "cancellation_error"
    }
]
```

Payment Intent Cutoff Time Passed Error Example

```json
[
    {
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "Payment Intent cannot be canceled as the cutoff time (23:59:00) has passed.",
        "code": "cancellation_error"
    }
]
```

**Cause**

This error can occur when:

- You attempted to cancel a payment intent that was not scheduled.
- You sent through your cancellation request past the 23:59:00 (GMT-3) cutoff time the day before the scheduled settlement date.


## 400 does_not_exist

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |



```json Does Not Exist Example
[
    {
        "field": "institution",
        "request_id": "744da6621cb09b3cbb8271d89fe09060",
        "message": "Object with name=narnia does not exist.",
        "code": "does_not_exist"
    }
]
```

**Cause**

You sent a request where you provided a value that doesn't exist in the Belvo database. For example:


```json Request with Non-Existent Institution Example
{
    "institution": "narnia", // This institution does not exist in the Belvo database.
    "username": "bnk100",
    "password": "full"
}
```

**Solution**

Check the error message to see in which field you provided an incorrect value. Then:

- Make sure that you haven't made any typos.
- Check if the value you are providing should be present in our database (for example, if you make a request for a link that wasn't registered yet, you will receive an error).


## 400 duplicated

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | Yes |
| Enrichment | Request | No |



```json Duplicated Link Example
[ 
    {
        "request_id": "744da6621cb09b3cbb8271d89fe09060",
        "message": "Link already exists",
        "code": "duplicated",
        "institution_user_id": "4jlgn6vL7yifxMlhwFwTjbbzYxYoEEkJqK_CJhhZetI="
    }
]
```

**Cause**

This error can occur when:

- You tried to create a link that has already been associated with your account.
- Your user tried to create a link with an account they have already connected.


**Solution**

You can either:

- Query your database to find the `institution_user_id` and check whether the link associated link `id` is still valid using the Get a link's details request. If the `status` is not `valid`, then prompt your user to update their credentials by using the the Belvo widget in update mode.
- Query your database to find the `institution_user_id` and use the associated link `id` to delete the link from the Belvo database using the Delete a link request. Once you have deleted the link, you can ask your user to connect their account again.


## 400 null

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |



```json Null Field Example
[
    {
        "field": "institution",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "This field may not be null.",
        "code": "null"
    }
]
```

**Cause**

You made a request without providing data in a required field.  For example:


```json Null Field Request Example
{
    "institution": , // This field is required.
    "username": "bnk100",
    "password": "full",
}
```

**Solution**

Check the error message to see which field you need to provide. If you're not sure what information to provide or the format, just check our API reference documentation.

## 400 required

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |
| Payment Initiation | Request | No |



```json Required Field Example
[
    {
        "field": "username",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "This field is required.",
        "code": "required"
    }
]
```

**Cause**
You sent a request without a required field. For example:


```json Required Field Request Example
{
    "institution": "erebor_mx_retails",
    "password": "full"
    // When you are registering a new link, you must provide a username.
}
```

**Solution**

- Check the error message to see which field you need to provide. If you're not sure what information to provide or the format, just check our API reference documentation.


## 400 institution_down

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Institution | Yes |
| Enrichment | Institution | Yes |
| Payment Initiation | N/A | N/A |



```json Institution Down Example
[
  {
    "code": "institution_down",
    "message": "The financial institution is down, try again later",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]
```

**Cause**

This error occurs when the institution's website that you're trying to access is down due to maintenance or other issues, which means Belvo is unable to create new links or retrieve new data.

**Solution**

You can retry accessing the institution later. Make sure to subscribe to our Institutions Status Page to know as soon as an institution is unavailable.

You can remove an institution that is currently not available by using the`institutions` parameter in the startup configuration and omitting the institution from the list.

**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | Something went wrong | The institution you tried to access is temporarily unavailable. Please come back in a bit and we will be able to process your request |
| 🇧🇷 Portuguese | Ocorreu um erro | Esta instituição está temporariamente inacessível. Tente novamente mais tarde e poderemos processar sua solicitação |
| 🇪🇸 Spanish | Ha habido un error | Esta institución está temporalmente inaccesible. Por favor, inténtalo de nuevo más tarde y podremos procesar tu petición |


## 400 institution_inactive

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Institution | Yes |
| Enrichment | Institution | Yes |
| Payment Initiation | N/A | N/A |



```json Institution Inactive Example
[
  {
    "code": "institution_inactive",
    "message": "The institution has been temporarily deactivated",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]
```

**Cause**

This error occurs when we (Belvo) have deactivated the institution in our API.

**Solution**

You can retry later, once Belvo has reactivated the institution.

## 400 institution_unavailable

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Institution | Yes |
| Enrichment | Institution | Yes |
| Payment Initiation | N/A | N/A |



```json Institution Unavailable Example
[
  {
    "code": "institution_unavailable",
    "message": "The financial institution is unavailable",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]
```

**Cause**

This error occurs when the institution's website that you're trying to access is down due to maintenance or other issues, which means Belvo is unable to create new links or retrieve new data.

**Solution**

You can retry accessing the institution later. Make sure to subscribe to our Institutions Status Page to know as soon as an institution is unavailable.

You can remove an institution that is currently not available by using the `institutions` parameter in the startup configuration and omitting the institution from the list.

**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | Something went wrong | The institution you tried to access is temporarily unavailable. Please come back in a bit and we will be able to process your request. |
| 🇧🇷 Portuguese | Ocorreu um erro | O serviço está temporariamente inacessível. Tente novamente mais tarde e poderemos processar sua solicitação |
| 🇪🇸 Spanish | Ha habido un error | Esta institución está temporalmente inaccesible. Por favor, inténtalo de nuevo más tarde y podremos procesar tu petición |


## 400 invalid

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |
| Payment Initiation | Request | No |


Wrong Date Format Example

```json Wrong Date Format Example
[
  {
    "field": "date_to",
    "request_id": "a7ad9a4ad8b13f8f800f8f5b69c7856f",
    "message": "Date has wrong format. Use one of these formats instead: YYYY-MM-DD.",
    "code": "invalid"
  }
]
```

Wrong UUID Format Example

```json Wrong UUID Format Example
[
  {
    "field": "link",
    "request_id": "448f2b58fc88b2c5a9db6c9175494950",
    "message": "YTZjMDA3YjktZTk5Yy00MDczLTgzNGItOGM3NzA1MTMyZGU3 is not a valid UUID.",
    "code": "invalid"
  }
]
```

Incorrect Fetch Resources Example

```json Incorrect Fetch Resources Example
[
  {
    "field": "resources",
    "request_id": "a7ad9a4ad8b13f8f800f8f5b69c7856f",
    "message": "The institution only supports the following resources: {1}, {2}",
    "code": "invalid"
  }
]
```

**Cause**

You sent a request where you provided a value in an invalid format. This could include:

- The format of the login credentials is incorrect.
- The date format is incorrect.
- The UUID is not valid.
- The terminal_id is not valid.
- The form_id is not valid.
- The resources you've included in `fetch_resources` are not supported by the institution.


For example:

Wrong Date Format Request Example

```json Wrong Date Format Example
{
  "link": "a6c007b9-e99c-4073-834b-8c7705132de7",
  "date_from": "2020-01-01",
  "date_to": "2020-02" // Here, the date format must be YYYY-MM-DD 
}
```

Wrong UUID Format Request Example

```json Wrong UUID Format Example
{
  "link": "a6c007b9-e99c" // Here, the link ID is not a valid UUID.
}
```

**Solution**

Check the error message to see which field is invalid and why. Then, if you need more information, check our API docs to know what the valid format for the field is.

## 400 invalid_choice

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |



```json Invalid Choice Example
[
    {
        "field": "access_mode",
        "request_id": "ce49b6af6710bb0c7a2a456c223dde21",
        "message": "\"Dominik\" is not a valid choice.",
        "code": "invalid_choice"
    }
]
```

**Cause**
You made a request where in one of the fields you provided a value that wasn't valid (for example, it may only accept certain strings, much like an enum). For example:


```json Invalid Choice Request Example
{
    "institution": "erebor_mx_retail",
    "username": "bnk100",
    "password": "full",
    "access_mode": "Australia" // This is not a valid choice, as in the documentation it states that it is an enum: single or recurrent
}
```

**Solution**

- Check the error message to see in which field you provided an incorrect value. Then check our documentation to see what value you should provide for this field.


## 400 invalid_credentials_storage

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |



```json Invalid Credentials Storage Example
[
    {
        "request_id": "ce49b6af6710bb0c7a2a456c223dde21",
        "message": "Recurrent links must store the credentials",
        "code": "invalid_credentials_storage"
    }
]
```

**Cause**
You made a request where for a recurrent link you set the `credentials_storage` parameter to `nostore` or to a date range between `1d` to `365d`.


```json Invalid Credentials Storage Request Example
{
    "institution": "tatooine_mx_fiscal",
    "username": "PFIS010101000",
    "password": "individual",
    "access_mode": "recurrent",
    "credentials_storage": "nostore" // For recurrent links, this must be set to store
}
```

**Solution**

- If you want to create a recurrent link, change the value of `credentials_storage` to `store`.
- If you want to create a single link and not store credentials, change the `access_mode` to `single`.


## 400 invalid_fetch_resources

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |



```json Invalid Fetch Resources Example
[
    {
        "request_id": "ce49b6af6710bb0c7a2a456c223dde21",
        "message": "Single links without stored credentials must fetch resources",
        "code": "invalid_fetch_resources"
    }
]
```

**Cause**
You attempted to create a link where you set the`credentials_storage` parameter to `nostore`  and did not pass any resources in the `fetch_resources` parameter. For links where we don't store credentials, you must pass at least one resource in`fetch_resources`.


```json Invalid Fetch Resources Request Example
{
    "institution": "tatooine_mx_fiscal",
    "username": "PFIS010101000",
    "password": "individual",
    "access_mode": "recurrent",
    "credentials_storage": "nostore",
  	"fetch_resources": []
}
```

**Solution**

List the resources you want to retrieve in the `fetch_resources` parameter. For example: `"fetch_resources": ["ACCOUNTS", "OWNERS", "TRANSACTIONS"]` .

## 400 invalid_link

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Link | No |
| Enrichment | Link | No |
| Payment Initiation | N/A | N/A |



```json Invalid Link Example
[
  {
    "code": "invalid_link",
    "message": "The link has been invalidated. You may need to update link credentials",
    "request_id": "9b7b283c6efa449c9c028a16b5c249fd"
  }
]
```

**Cause**

This error when you try to access an account but the user credentials are no longer valid, prompting an error from the institution.

A Link's status changes from `valid` to `invalid` after six unsuccessful POST requests

**Solution**

Ask your user to provide their updated credentials. To make things easier, we highly recommend you use our Widget in Update Mode.

## 400 invalid_period

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | N/A | N/A |



```json Invalid Period Example
[
    {
        "message": "The number of days between date_from and date_to must be at least 90 days",
        "code": "invalid_period",
        "request_id": "a66a4fdae4ab8cfc1ed9ee9246aa6890"
    }
]
```

**Cause**

This error occurs when you request incomes for a link within a given date range, however, the period between `date_from` and `date_to` is less than 90 days.

**Solution**

Make sure that the period between `date_from` and `date_to` is equal to or greater than 90 days.

## 400 login_error

We are currently refining our `login_error` messages to provide greater granularity and improve troubleshooting

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Link | Yes |
| Enrichment | Link | Yes |



```json Login Error Example
[
    {
        "code": "login_error",
        "message": "Invalid credentials provided to login to the institution.",
        "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
    }
]
```

**Cause**

This error can occur when:

- the credentials that your user provides are incorrect or missing.
- the MFA token your user provides is not supported by Belvo
- there is an issue with the institution that prevents logins.
- the user's account is either locked or the user does not have permission to access their internet banking.


Below is a list of possible error `message`s you may receive:

- Invalid credentials provided to login to the institution.
- A MFA token is required by the institution, but it’s not supported yet by Belvo.
- Impossible to login, something unexpected happened while logging into the institution. Try again later.
- Login not attempted due to invalid credentials.
- Missing credentials to login to the institution.
- The user account access was forbidden by the institution.
- The user account is locked, user needs to contact the institution to unlock it.


**Solution**

- Ask your user to provide their correct credentials or MFA token. Use our widget to make it even easier (we do all the heavy lifting for you).
- Ask your user to confirm with their bank that their account is active and that it isn't blocked.
- If there is an issue with the institution, try logging in at a later time.


## 400 max_digits

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | N/A | N/A |
| Enrichment | N/A | N/A |
| Payment Initiation | Request | No |



```json Wrong Amount Format Example
[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "Ensure that there are no more than 12 digits in total.",
        "code": "max_digits"
    }
]
```

**Cause**
You sent a request with the wrong amount format.

**Solution**

Check the error message to see why the amount format is invalid. If you're not sure what information to provide or the format, just check our API reference documentation to know what the valid format for the field is.

## 400 max_decimal_places

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | N/A | N/A |
| Enrichment | N/A | N/A |
| Payment Initiation | Request | No |



```json Too Many Decimal Places Example
[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "Ensure that there are no more than 2 decimal places.",
        "code": "max_decimal_places"
    }
]
```

**Cause**
You sent a request with the wrong amount format (too many decimal places).

**Solution**

Check the error message to see why the amount format is invalid. If you're not sure what information to provide or the format, just check our API reference documentation to know what the valid format for the field is.

## 400 min_value

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | N/A | N/A |
| Enrichment | N/A | N/A |
| Payment Initiation | Request | No |



```json Minimum Amount Value Example
[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "Ensure this value is greater than or equal to 0.01.",
        "code": "min_value"
    }
]
```

**Cause**
You sent a request with the wrong amount format (the amount is less than the minimum value allowed).

**Solution**

Check the error message to see why the amount format is invalid. If you're not sure what information to provide or the format, just check our API reference documentation to know what the valid format for the field is.

## 400 not_a_list

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |
| Payment Initiation | Request | No |



```json Not a List Example
[
    {
        "message": "Expected a list but got type \"str\".",
        "code": "not_a_list",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]
```

**Cause**
You sent a request where instead of sending an array of data, you sent through just a list. For example:

Incorrect Example

```json Incorrect Example
{
  "fetch_resources": "ACCOUNTS,OWNERS" // Here, fetch_resources has to be an array of values
}
```

Correct Example

```json Correct Example
{
  "fetch_resources": ["ACCOUNTS", "OWNERS"]
}
```

**Solution**

Check your JSON request and consult our documentation to see which field should be an array.

## 400 parse_error

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |
| Payment Initiation | Request | No |



```json Parse Error Example
[
    {
        "message": "JSON parse error - Expecting property name enclosed in double quotes: line 3 column 1 (char 54)",
        "code": "parse_error",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]
```

**Cause**
You sent a request with invalid JSON. For example:


```json Parse Error Request Example
{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7", // Here, the JSON is not valid because it has a trailing comma
}
```

**Solution**

Check the JSON payload (perhaps you're just missing a comma or quotation mark) and try again.

## 400 session_expired

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | Yes |
| Enrichment | Request | Yes |



```json Session Expired Example
[
  {
    "code": "session_expired",
    "message": "The session you are trying to resume has expired, please start again from register/retrieve endpoint",
    "request_id": "6e7b283c6efa449c9c028a16b5c249fa"
  }
]
```

**Cause**

This error occurs when you try to resume a request session that has already expired. This is usually because the user took too long to provide their authentication token.

> For requests that require a token, there is a period of time where the user can provide their token. The period varies from institution to institution. You can check how much time the user has to enter their token by using the `expiry` parameter in the 428 `token_required` response.


**Solution**

Unfortunately, you'll need to start the entire login process with your user again.

**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | Please try again! | Please try again to link your account as the session with this institution just expired |
| 🇧🇷 Portuguese | Por favor, faça login novamente | A sessão com essa instituição expirou. Por favor, digite suas credenciais novamente |
| 🇪🇸 Spanish | Por favor, ingresa de nuevo | Por favor, ingresa de nuevo tus credenciales ya que la sesión con esta institución ha expirado |


## 400 session_expired_ob

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | Yes |



```json Session Expired OB Example
[
  {
    "code": "session_expired_ob",
    "request_id": "6e7b283c6efa449c9c028a16b5c249fa"
  }
]
```

**Cause**

You can receive this error due to the following reasons:

1. The `access_token` you generated was not used within the 10 minute expiration period.
2. Instead of generating a new `access_token` for the widget for the given user, you used an `access_token` generated for another user that already created a link using the widget.
3. Your user did not click on the **Ir para a instituição** (Go to the institution) button in the widget within 60 seconds of the screen appearing.


**Solution**

Unfortunately, you'll need to start the widget process with your user again. Please make sure that you:

1. Ensure that you use the `access_token` to generate the widget as soon as it is created. If 10 minutes or more pass, you will need to create a new `access_token`.
2. Ensure that you always create a new `access_token` for every user.
3. Our UX team is improving the flow so as to prompt the user to continue the flow within the allotted 60 seconds.


**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | Session expired | Your connection session expired, please refresh the page to try again to link your account |
| 🇧🇷 Portuguese | Sessão expirada | Sua sessão expirou, atualize a página e tente vincular sua conta novamente. |


## 400 too_many_sessions

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Link | Yes |
| Enrichment | Link | Yes |
| Payment Initiation | Link | Yes |



```json Too Many Sessions Example
[
	{
		"code": "too_many_sessions",
		"message": "Impossible to login, a session is already opened with the institution for these credentials",
		"request_id": "3e7b283c6efa449c9c028a16b5c249fd"
	}
]
```

**Cause**

This error occurs when:

- a user is attempting to log in to their institution via Belvo while also already being logged in to their institution on a web browser or mobile app.
- you make a request for information while Belvo is scraping data from the institution for that user.


**Solution**

Try:

- Informing your user to close their web and app sessions for the given institution.
- Waiting 120 seconds and retrying your request, ensuring that Belvo has finished the data scraping process.


**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | A session is already open | It seems you are logged in to your account with another device. This institution only allows one logged in session at a time. Log out and try linking your account again. |
| 🇧🇷 Portuguese | Muitas sessões abertas | Parece que já existe uma sessão aberta nesta instituição com seu usuário. Esta instituição permite apenas uma sessão aberta por vez |
| 🇪🇸 Spanish | Demasiadas sesiones abiertas | Parece que ya hay una sesión abierta en esta institución con tu usuario. Esta institución solo permite una sesión abierta a la vez. |


## 400 unavailable_data

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | N/A | No |
| Payment Initiation | N/A | N/A |



```json Unavailable Data Example
[
    {
        "message": "The institution did not return any data for the request.",
        "code": "unavailable_data",
        "request_id": "c76f4d0320b923eb3068f5e2c0fab18f"
    }
]
```

**Cause**

This error occurs when your request was correctly formed and sent, however, the institution did not return any data for your request.

**Solution**

We recommend first checking our Institution Status Page to see if there is any incident with the institution that is prohibiting data extraction. If no incidents are active for the institution, you can retry the request.  If you keep getting this error, contact our support team, making sure to include the `request_id` that you receive in the message.

## 400 unconfirmed_link

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Link | No |
| Enrichment | Link | No |
| Payment Initiation | N/A | N/A |



```json Unconfirmed Link Example
[
    {
        "message": "The link creation has not been completed yet",
        "code": "unconfirmed_link",
        "request_id": "c76f4d0320b923eb3068f5e2c0fab18f"
    }
]
```

**Cause**

This error occurs when you try to access a link that was paused previously (and as such is not active now).

A Link's status is set to `unconfirmed_link` when your user has not completed the Link creation process successfully (for example, they might not provide a valid MFA token)

**Solution**

Ask your user to provide an MFA token through our widget in update mode to complete a first login. After the user successfully completes the process, you will be able to retrieve data.

## 400 unsupported_operation

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | N/A | N/A |


Resource Not Supported Error Example

```json Resource Not Supported Example
[
  {
    "message": "The resource you are trying to access is not supported by this institution",
    "code": "unsupported_operation",
    "request_id": "a66a4fdae4ab8cfc1ed9ee9246aa6890"
  }
]
```

Fetch Historical Error Example

```json Fetch Historical Error Example
[
  {
    "message": "For single links, you must set fetch_historical to true when using the resources request parameter.",
    "code": "unsupported_operation",
    "request_id": "a66a4fdae4ab8cfc1ed9ee9246aa6890"
  }
]
```

**Cause**

This error occurs when:

- You try to access some data operation that Belvo does not support for an institution. For example, trying to access the **Transactions** resource for Fiscal institutions.
- You make a request that requires some business logic to be completed. For example, when using the `fetch_resources` parameter on single link creation, you must also set `fetch_historical` to true


**Solution**

Make sure that:

- The resource operation (for example requesting Transactions) is supported for that institution.
- Your request fulfills all the required business logic.


**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | Something went wrong | There was an error with your request. Please try again, and if the problem persists, we will try to fix it as soon as possible |
| 🇧🇷 Portuguese | Ocorreu um erro | Ocorreu um erro com a sua solicitação. Tente novamente e, se o problema persistir, o corrigiremos o mais breve possível |
| 🇪🇸 Spanish | Ha habido un error | Hemos tenido un error con tu petición. Por favor, inténtalo de nuevo y si el problema persiste, lo arreglaremos lo más pronto posible |


## 400 validation_error

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |
| Payment Initiation | N/A | N/A |



```json Validation Error Example
[
    {
        "message": "Bad request",
        "code": "validation_error",
        "request_id": "e912d014d7976c3172bb8e65c7a22194"
    }
]
```

**Cause**

You sent a request where:

- The credentials provided did not match the expected fields, leading to a field validation error from the institution.


For example:


```json Validation Error Request Example
{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7",
    "date_from": "2020-01-01",
    "date_to": "2021-03-30" // Between date_from and date_to there are more than 365 days
}
```

**Solution**

Get the details for the institution using our Institutions endpoint and check the `form_fields` object for information on what fields need to be provided and their format.

## 401 authentication_failed

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | N/A | N/A |



```json Authentication Failed Example
[
    {
        "message": "Invalid Secret Keys",
        "code": "authentication_failed",
        "request_id": "5c09677ecf78e1d4501547252a0c4e77"
    }
]
```

**Cause**

This error occurs when you try to make an API call using incorrect Belvo API credentials (either your secret key or secret password, or both, are incorrect).

**Solution**

Check the credentials that you are using against the ones in your dashboard. Perhaps you're using your sandbox credentials to access production data (or vice versa).  Note: If you're unsure about your secretPassword, check the confirmation email that you received from Belvo.

## 401 consent_without_accounts

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | N/A | N/A |
| Payment Initiation | N/A | N/A |



```json Consent Without Accounts Example
[
    {
        "message": "Information cannot be retrieved as the consent has no associated accounts",
        "code": "consent_without_accounts",
        "request_id": "5c09677ecf78e1d4501547252a0c4e77"
    }
]
```

**Cause**

This error occurs when your user has removed accounts associated with the consent they provided. For example, when your user first generated their consent, they had a checking and a loan account at the institution but has closed those accounts since then.

**Solution**

Reach out to your user to confirm whether they have removed their account and ask them to generate a new consent at their current institution.

## 403 access_to_production_denied

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | Belvo | No |



```json Access to Production Denied Example
[
    {
        "message": "You don’t have access to production API.",
        "code": "access_to_production_denied",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]
```

**Cause**

This error occurs when you try to access Belvo's production environment without the correct permissions.

**Solution**
Contact our sales team to request access to production environment.

## 403 access_to_resource_denied

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | N/A | N/A |



```json Access to Resource Denied Example
[
    {
        "message": "You don't have access to this resource.",
        "code": "access_to_resource_denied",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]
```

**Cause**

This error occurs when you try to access a Belvo's resource without the correct permissions.

**Solution**
Contact our sales team to request access to this resource.

## 403 Forbidden

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |



```html
<html><head><title>403 Forbidden</title></head><body>

<center><h1>403 Forbidden</h1></center>

<hr><center>openresty/1.15.8.2</center>

</body></html>
```

**Cause**

This error occurs when you make a large volume of requests (over 80 requests in 30 seconds) in quick succession from the same IP address.

**Solution**

If you expect to consistently have large volumes of calls from the same IP address, please reach our to our Customer Success team.

## 403 permission_denied

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | Belvo | No |


**Cause**

This error occurs when we (Belvo) are forbidden to access a certain resource in the institution, or you have exceeded your request limit.

**Solution**
If you were able to access this resource previously, retry later. We (Belvo) actively monitor these errors and assign engineers to correct the situation as soon as possible.

## 403 quota_limit_reached

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | N/A | N/A |



```json Quota Limit Reached Example
[
    {
        "message": "The quota limit has been reached.",
        "code": "quota_limit_reached",
        "request_id": "1d1c4f427dac394a96c3fa49568f2a38"
    }
]
```

The `quota_limit_reached` is only applicable for the development environment

**Cause**

This error occurs when you have exceeded the Link limit in the development environment.

**Solution**

To keep using the development environment, you need to delete enough Links to be below the environment's limit.

## 404 not_found

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Request | No |
| Enrichment | Request | No |
| Payment Initiation | Request | No |


Object Not Found Error Example

```json Object Not Found Error Example
[
  {
    "message": "Not found.",
    "code": "not_found",
    "request_id": "1d1c4f427dac394a96c3fa49568f2a38"
  }
]
```

Credentials Not Found Error Example

```json Credentials Not Found Error Example
[
  {
    "message": "The credentials of this link have expired",
    "code": "expired_credentials",
    "request_id": "4d3de3930431496799eafc5c91e5bcfe"
  }
]
```

**Cause**

You made a request where you:

- provided the wrong URL.
- used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.
- made a request for a link where the `credentials_storage` was set to `no_store` or to `30d`, and Belvo no longer has these credentials stored to retrieve information.


**Solution**

Make sure that:

- You are using the correct URL (check for typos and our API reference documentation).
- You are using an ID that is associated with your Belvo account.


In the case where the link was created with the `credentials_storage` was set to `no_store` or `30d`, you'll need to ask the user to re-connect their account.

## 405 method_not_allowed

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | Belvo | No |



```json Method Not Allowed Example
[
    {
        "message": "Method \"PATCH\" not allowed.",
        "code": "method_not_allowed",
        "request_id": "8ea4cd36ad39db3823b89b31aea74581"
    }
]
```

**Cause**

This error occurs when you try to use an API method that is not allowed for the given resource (for example, a PATCH request for Fiscal endpoints).

**Solution**

Double check what methods are allowed for the given resource in our API Reference Documentation.

## 408 request_timeout

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |
| Payment Initiation | Belvo | No |



```json Request Timeout Example
[
  {
    "code": "request_timeout",
    "message": "The request timed out, you can retry asking for less data by changing your query parameters",
    "request_id": "5c7b283c6efa449c9c028a16b5c249fd"
  }
]
```

**Cause**

Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out, which is set to five (5) minutes. A timeout occurs when there is a very large amount of data and everything could not be obtained within the allotted time.

> For example, if an account has more than 2000 transactions per account per month, you may receive a `request_timeout` error.


**Solution**

When a timeout occurs, our API still saves as much data as it could retrieve. So, you can try making the same request again and recover all the data successfully.

If you keep receiving timeout errors for several links, or three timeouts for the same link, report it to Belvo and provide the `request_id`s.

**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | The connection has timed out | The response took too long and the connection could not be established successfully. Please try again in a few minutes. |
| 🇧🇷 Portuguese | Tempo limite de conexão atingido | O tempo de resposta está demorando mais do que o normal e a conexão não pode ser estabelecida. Por favor, tente novamente em alguns minutos. |
| 🇪🇸 Spanish | La conexión ha expirado | El tiempo de respuesta ha sido demasiado largo y la conexión no se ha podido establecer. Por favor, inténtalo de nuevo en unos minutos. |


## 409 link_refreshed

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Link | No |
| Enrichment | Link | No |



```json Link Refreshed Error Example
[
  {
    "code": "link_refreshed",
    "message": "The link has already been refreshed. Please wait X minutes before trying again.",
    "request_id": "9e7b283c6efa449c9c028a16b5c249fb"
  }
]
```

**Cause**

This error occurs when you make a request to the Trigger a historical update for a link method for a link that has been refreshed in the last 10 minutes.

**Solution**

Wait for the cooldown period to pass before making another request for the same link. The error message will indicate how many minutes you need to wait.

## 428 activation_required

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Institution | No |
| Enrichment | Institution | No |
| Payment Initiation | N/A | N/A |



```json Activation Required Example
[
  {
    "code": "activation_required",
    "message": "This user doesn't have web access activated yet.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249jk"
  }
]
```

**Cause**

This error occurs when the user has not activated their internet banking access.

**Solution**

Ask the user to first activate their internet banking access and then ask them to connect their account again.

## 428 token_required

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Link | Yes |
| Enrichment | Link | Yes |



```json Token Required Example
[
  {
    "code": "token_required",
    "message": "A MFA token is required by the institution to login",
    "request_id": "8c7b283c6efa449c9c028a16b5c249fa",
    "session": "2675b703b9d4451f8d4861a3eee54449",
    "expiry": 9600,
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "token_generation_data": {
      "instructions": "Use this code to generate the token",
      "type": "numeric",
      "value": "12345"
    }
  }
]
```

**Cause**

This error occurs when the institution requires MFA to log in.

**Solution**

See our article on how to handle MFA. However, we highly recommend you use our Connect Widget as we'll handle these types of errors for you and walk your user through the steps to provide their authentication token.

**Widget error message**

In the case that your user incorrectly enters their token (or the token they enter is expired) while using the widget, the following error messages are displayed:

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | Invalid token | It looks like the token has expired, generate a new one and try again. |
| 🇧🇷 Portuguese | Token inválido | É provável que o token tenha expirado, gere um novo e tente novamente |
| 🇪🇸 Spanish | Token inválido | Es probable que el token haya caducado, genera uno nuevo y vuelve a intentarlo |


## 500 service_unavailable

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | No |
| Enrichment | Belvo | No |



```json Service Unavailable Example
[
  {
    "code": "service_unavailable",
    "message": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution",
    "request_id": "4a7b283c6efa449c9c028a16b5c249fd"
  }
]
```

**Cause**

This error occurs when we (Belvo) have encountered an internal system error (sorry about that).

**Solution**

You can retry later. If you keep getting this error, contact our support team, making sure to include the `request_id` that you receive in the message.

## 500 unexpected_error

| API | Error type | Reflected in widget? |
|  --- | --- | --- |
| Aggregation | Belvo | Yes |
| Enrichment | Belvo | Yes |
| Payment Initiation | Belvo | Yes |



```json Unexpected Error Example
[
  {
    "code": "unexpected_error",
    "message": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution",
    "request_id": "4a7b283c6efa449c9c028a16b5c249fd"
  }
]
```

**Cause**

This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.

This type of error can be intermittent or persistent.

**Solution**

We recommend that you retry making your original request a **maximum of three times**, in case that the issue is intermittent.

If the error keeps occurring with the same request, contact our support team, making sure to include the `request_id` that you receive in the error message.

**Widget error message**

| Language | Error title | Error description |
|  --- | --- | --- |
| 🇬🇧 English | Something went wrong | There was an error linking your account. Please try again, and if the problem persists, we will try to fix it as soon as possible. |
| 🇧🇷 Portuguese | Ocorreu um erro | Ocorreu um erro ao vincular sua conta. Tente novamente e, se o problema persistir, o corrigiremos o mais breve possível |
| 🇪🇸 Spanish | Ha habido un error | Hemos tenido un error vinculando tu cuenta. Por favor, inténtalo de nuevo y si el problema persiste, lo arreglaremos lo más pronto posible |