API and Widget Errors

On this page you'll find information regarding errors that you might encounter when using the Belvo API, and how to solve them.

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.

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

Error typeReflected in widget?
InstititutionNo
[
  {
    "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 blank

Error typeReflected in widget?
RequestNo
[
    {
        "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 does_not_exist

Error typeReflected in widget?
RequestNo
[
    {
        "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 null

Error typeReflected in widget?
RequestNo
[
    {
        "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

Error typeReflected in widget?
RequestNo
[
    {
        "field": "username",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "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"
}

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

Error typeReflected in widget?
InstitutionYes
[
  {
    "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

LanguageError titleError description
🇬🇧
English
Something went wrongThe 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 erroEsta instituição está temporariamente inacessível. Tente novamente mais tarde e poderemos processar sua solicitação
🇪🇸
Spanish
Ha habido un errorEsta institución está temporalmente inaccesible. Por favor, inténtalo de nuevo más tarde y podremos procesar tu petición

400 institution_inactive

Error typeReflected in widget?
InstitutionYes
[
  {
    "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

Error typeReflected in widget?
InstitutionYes
[
  {
    "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

LanguageError titleError description
🇬🇧
English
Something went wrongThe 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 erroO serviço está temporariamente inacessível. Tente novamente mais tarde e poderemos processar sua solicitação
🇪🇸
Spanish
Ha habido un errorEsta institución está temporalmente inaccesible. Por favor, inténtalo de nuevo más tarde y podremos procesar tu petición

400 invalid

Error typeReflected in widget?
RequestNo
[
    {
        "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"
    }
]

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 data format is incorrect.
  • The UUID is not valid.

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.
}

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

Error typeReflected in widget?
RequestNo
[
    {
        "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_link

Error typeReflected in widget?
LinkNo
[
  {
    "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

Error typeReflected in widget?
BelvoNo
[
    {
        "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.

Error typeReflected in widget?
LinkYes
[
  {
    "code": "login_error",
    "message": "Invalid credentials provided to login to the institution",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

Cause

This error occurs when the credentials that your user provides are incorrect.

Solution

Ask your user to provide their correct credentials. Use our widget to make it even easier (we do all the heavy lifting for you).


400 parse_error

Error typeReflected in widget?
RequestNo
[
    {
        "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

Error typeReflected in widget?
LinkYes
[
  {
    "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

LanguageError titleError 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 novamenteA sessão com essa instituição expirou. Por favor, digite suas credenciais novamente
🇪🇸
Spanish
Por favor, ingresa de nuevoPor favor, ingresa de nuevo tus credenciales ya que la sesión con esta institución ha expirado

400 too_many_sessions

Error typeReflected in widget?
LinkYes
[
    {
        "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

LanguageError titleError description
🇬🇧
English
A session is already openIt 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 abertasParece 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 abiertasParece 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 unconfirmed_link

Error typeReflected in widget?
LinkNo
[
    {
        "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).

Se intentó consumir data de un link con estatus unconfirmed_link.

📘

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

Error typeReflected in widget?
BelvoYes
[
    {
        "message": "The resource you are trying to access is not supported by this institution",
        "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 Statements resource for gig-economy accounts or balances for Fiscal institutions.

Solution

Double check the resources that the institution supports in our Institutions guide.

Widget error message

LanguageError titleError description
🇬🇧
English
Something went wrongThere 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 erroOcorreu 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 errorHemos 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

Error typeReflected in widget?
RequestNo
[
    {
        "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

Error typeReflected in widget?
BelvoNo
[
    {
        "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.


403 permission_denied

Error typeReflected in widget?
BelvoNo

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.


404 not_found

Error typeReflected in widget?
RequestNo
[
    {
        "message": "Not found.",
        "code": "not_found",
        "request_id": "1d1c4f427dac394a96c3fa49568f2a38"
    }
]

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.

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.

405 method_not_allowed

Error typeReflected in widget?
BelvoNo
[
    {
        "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

Error typeReflected in widget?
BelvoYes
[
  {
    "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. A timeout occurs when there is a very high 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

LanguageError titleError description
🇬🇧
English
The connection has timed outThe 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 atingidoO 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 expiradoEl 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.

428 activation_required

Error typeReflected in widget?
InstitutionNo
[
  {
    "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

Error typeReflected in widget?
LinkYes
[
  {
    "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:

LanguageError titleError description
🇬🇧
English
Invalid tokenIt 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álidoEs probable que el token haya caducado, genera uno nuevo y vuelve a intentarlo

500 service_unavailable

Error typeReflected in widget?
BelvoNo
[
  {
    "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 us at [email protected], making sure to include the request_id that you receive in the message.


500 unexpected_error

Error typeReflected in widget?
BelvoYes
[
  {
    "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 reqquest, please contact as at [email protected], making sure to include the request_id that you receive in the error message.

Widget error message

LanguageError titleError description
🇬🇧
English
Something went wrongThere 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 erroOcorreu um erro ao vincular sua conta. Tente novamente e, se o problema persistir, o corrigiremos o mais breve possível
🇪🇸
Spanish
Ha habido un errorHemos tenido un error vinculando tu cuenta. Por favor, inténtalo de nuevo y si el problema persiste, lo arreglaremos lo más pronto posible


Did this page help you?