Link errors

On this page you'll find information regarding errors that you might encounter when interacting with links, and how to solve them.

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.

Solution

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

400 login_error

[
  {
    "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 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 session that has already expired. This is usually because the user took too long to provide their authentication token.

Solution

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

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.
  • 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 sessions for the given institution.
  • Waiting 120 seconds and retrying your request, ensuring that Belvo has finished the data scraping process.

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

Solution

Ask your user to provide an MFA token through our widget in update mode to complete a first login.

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.


Did this page help you?