Institution Errors

Guide to troubleshooting Institution errors

INSTITUTION_DOWN

The financial institution is down, either for maintenance or due to an infrastructure issue with their systems.
Sample user-facing error message
Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • The institution is undergoing scheduled maintenance.
  • The institution is experiencing temporary technical problems.
Troubleshooting steps

If the error persists, please submit a 'Persistent HTTP 500 errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_DOWN",
5 "error_message": "this institution is not currently responding to this request. please try again soon",
6 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}

INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT

Institution not enabled in this environment
Common causes

You're referencing an institution that exists, but is not enabled for this environment (e.g. calling a Sandbox endpoint with the ID of an institution that is not enabled there).

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT",
5 "error_message": "Institution not enabled in this environment",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

INSTITUTION_NOT_FOUND

This institution was not found. Please check the ID supplied
Common causes

A call was made using an institution_id that does not exist.

Troubleshooting steps
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_FOUND",
5 "error_message": "this institution was not found. Please check the ID supplied",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

INSTITUTION_NOT_RESPONDING

The financial institution is failing to respond to some of our requests. Your user may be successful if they retry another time.
Sample user-facing error message
Couldn't connect to your institution: If you need to use this app immediately, we recommend trying another institution. Errors like this are usually resolved quickly, so you may want to try the same account again later.
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • The institution is experiencing temporary technical problems.
Troubleshooting steps

If the error persists, please submit a 'Persistent HTTP 500 errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_RESPONDING",
5 "error_message": "this institution is not currently responding to this request. please try again soon",
6 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}

INSTITUTION_NOT_AVAILABLE

The financial institution is not available this time.
Link user experience

Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account.

Common causes
  • Plaid’s connection to an institution is temporarily down for maintenance or other planned circumstances.
Troubleshooting steps

If the error persists, please submit a 'Persistent HTTP 500 errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NOT_AVAILABLE",
5 "error_message": "this institution is not currently responding to this request. please try again soon",
6 "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}

INSTITUTION_NO_LONGER_SUPPORTED

Plaid no longer supports this financial institution.
Sample user-facing error message
Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time.
Common causes
  • The financial institution is no longer supported on Plaid's platform.
  • The institution has switched from supporting non-OAuth-based connections to requiring OAuth-based connections.
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_NO_LONGER_SUPPORTED",
5 "error_message": "this institution is no longer supported",
6 "display_message": "This financial institution is no longer supported. We apologize for the inconvenience.",
7 "request_id": "HNTDNrA8F1shFEW"
8}

UNAUTHORIZED_INSTITUTION

You are not authorized to create Items for this institution at this time.
Common causes
  • Access to this institution is subject to additional verification and must be manually enabled for your account.
  • You have not yet completed the OAuth registration requirements for the institution.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "UNAUTHORIZED_INSTITUTION",
5 "error_message": "not authorized to create items for this institution",
6 "display_message": "You are not authorized to create items for this institution at this time.",
7 "request_id": "HNTDNrA8F1shFEW"
8}

INSTITUTION_REGISTRATION_REQUIRED

Your application is not yet registered with the institution.
Common causes
  • Details about your application must be registered with this institution before use.
  • If your account has not yet been enabled for Production access, some institutions that require registration may not be available to you.
Troubleshooting steps
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "INSTITUTION_REGISTRATION_REQUIRED",
5 "error_message": "not yet registered to create items for this institution",
6 "display_message": "You must register your application with this institution before you can create items for it.",
7 "request_id": "HNTDNrA8F1shFEW"
8}

UNSUPPORTED_RESPONSE

The data returned from the financial institution is not valid.
Common causes
  • The data returned from the financial institution is not supported or is invalid.
1http code 400
2{
3 "error_type": "INSTITUTION_ERROR",
4 "error_code": "UNSUPPORTED_RESPONSE",
5 "error_message": "the data returned from the financial institution is not valid",
6 "display_message": "The data returned from the financial institution is not valid.",
7 "request_id": "HNTDNrA8F1shFEW"
8}