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:

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

[
  {
    "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

📘

* 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 [email protected] if you have any questions.

[
  {
    "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

[
    {
        "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

{
  "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",
                "pix_key": "RANDOM://6c1c236c-a035-4b80-ab12-e38f88ce82ab", // Pix key already registerted in Belvo.
     }
}

{
  "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

[
    {
        "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:

{
    "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

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

[
    {
        "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

[
    {
        "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:

{
    "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

[
    {
        "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

[
    {
        "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:

{
    "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

[
    {
        "field": "username",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "This field is required.",
        "code": "required"
    }
]

[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "This field is required.",
        "code": "required"
    }
]

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

{
    "institution": "erebor_mx_retails",
            // When you are registering a new link, you must provide a username.
    "password": "full"
}

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
           // When you are creating a payment link, you must provide an payment amount.
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

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

[
  {
    "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

400 institution_inactive

[
  {
    "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

[
  {
    "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

400 invalid

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

[
    {
        "field": "link",
        "request_id": "448f2b58fc88b2c5a9db6c9175494950",
        "message": "“YTZjMDA3YjktZTk5Yy00MDczLTgzNGItOGM3NzA1MTMyZGU3” is not a valid UUID.",
        "code": "invalid"
    }
]

[
    {
        "field": "payments_way",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "terminal_id": [
            {
                "message": "The terminal_id is invalid, try again or contact Belvo's support.",
                "code": "invalid"
            }
        ]
    }
]

[
    {
        "field": "payments_way",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "form_id": [
            {
                "message": "The form_id is invalid, try again or contact Belvo's support.",
                "code": "invalid"
            }
        ]
    }
]

[
    {
        "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:

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

{
    "link": "a6c007b9-e99c" // Here, the link ID is not a valid UUID.
}

{
     "holder": {
          "type": "BUSINESS",
          "information": {
               "name": "Trusty documentation services"
          }
     },
     "providers": {
          "payments_way": {
               "terminal_id": "1200", // Belvo provides you with the correct terminal_id you need to create a bank accont.
               "form_id": "3211", // Belvo provides you with the correct form_id you need to create a bank accont.
          }
     },
}

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

[
    {
        "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:

{
    "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

[
    {
        "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.

{
    "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

[
    {
        "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 thecredentials_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 infetch_resources.

{
    "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

[
  {
    "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

[
    {
        "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.

[
  {
    "code": "login_error",
    "message": "Invalid credentials provided to login to the institution",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "A MFA token is required by the institution, but it’s not supported yet by Belvo.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Impossible to login, something unexpected happened while logging into the institution. Try again later.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Login not attempted due to invalid credentials",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Missing credentials to login to the institution",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "The user account access was forbidden by the institution",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "The user account access was forbidden by the institution",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "The user account is locked, user needs to contact the institution to unlock it",
    "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.

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

[
    {
        "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. For example:

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
     "amount": 10000000000000000000,
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

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

[
    {
        "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. For example:

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
     "amount": 10.123,
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

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

[
    {
        "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. For example:

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
     "amount": 0.12,
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

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

[
    {
        "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:

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

{
    "fetch_resources": ["ACCOUNTS","OWNERS"],
}

Solution

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

400 parse_error

[
    {
        "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:

{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7", // Here, you should not have a trailing comma in your request
}

Solution

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

400 session_expired

[
  {
    "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

400 session_expired_ob

[
  {
    "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

400 too_many_sessions

[
	{
		"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

400 unavailable_data

[
    {
        "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

[
    {
        "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

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

[
    {
        "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 (check our institutions guide).
• Your request fulfills all the required business logic.

Widget error message

400 validation_error

[
    {
        "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:

{
    "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

[
    {
        "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

[
    {
        "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

[
    {
        "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

[
    {
        "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

<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

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

[
    {
        "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

[
    {
        "message": "Not found.",
        "code": "not_found",
        "request_id": "1d1c4f427dac394a96c3fa49568f2a38"
    }
]

[
    {
        "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

[
    {
        "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

[
  {
    "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_ids.

Widget error message

428 activation_required

[
  {
    "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

[
  {
    "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:

500 service_unavailable

[
  {
    "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

[
  {
    "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

Payment Initiation API last encountered errors

In addition to the standard list of errors, our Payments Initiation API also returns additional errors called last_errors that are specific to the payment flow. When a payment intent fails or encounters an error at some point along the payment flow, a last_error message is returned in the response to give you information about what went wrong. Depending on the specific error, you might need to prompt your customer to correct their payment information or start the payment flow again.

1. invalid_credentials
2. invalid_token
3. login_error
4. login_two_factor_error
5. missing_token_registration
6. payment_error
7. session_expired
8. unauthorized_credentials

Below we provide you with example messages, causes for the error, and how to troubleshoot them.

invalid_credentials

[
    {
      "error_code": "invalid_credentials",
      "error_message": "The credentials sent are incorrect, please try again."
    }
]

Cause

This error can occur when the credentials that your customer provides are incorrect.

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.

invalid_token

[
    {
      "error_code": "invalid_token",
      "error_message": "The token sent is incorrect or has expired, please try again."
    }
]

Cause

This error can occur when the MFA token your customer provides is invalid.

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.

login_error

[
    {
      "error_code": "login_error",
      "error_message": "Provider login error"
    }
]

Cause

This error can occur when something unexpected happened in the display_credentials_required next step.

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.

login_two_factor_error

[
    {
      "error_code": "login_two_factor_error",
      "error_message": "Provider login two factor error"
    }
]

Cause

This error can occur when something unexpected happened in the display_token_required next step.

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.

missing_token_registration

[
    {
      "error_code": "missing_token_registration",
      "error_message": "The user has no token configured in the bank."
    }
]

Cause

This error can occur when your user has not registered an MFA token with their bank.

📘

At present, this error only occurs for our PSE product with the following institutions:

• Bancolombia
• Banco de Bogota

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.

payment_error

[
    {
      "error_code": "payment_error",
      "error_message": "Unexpected error to confirm the payment"
    }
]

Cause

This error can occur when something unexpected happens during the payment confirmation process.

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.

session_expired

[
    {
      "error_code": "session_expired",
      "error_message": "Bank session was not found"
    }
]

Cause

This error occurs when you try to send a PATCH request after the session has already expired (the session expires after 10 minutes).

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.

unauthorized_credentials

[
    {
      "error_code": "unauthorized_credentials",
      "error_message": "Your credentials are not authorized. Please, contact the bank."
    }
]

Cause

This error occurs when your user has not provided the correct authorized credentials to log in to their institution.

Solution

Please check what the next step is in the payment intent process to complete the transaction. You can do this by making a Get details about a payment link request and checking the next_step field.