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.

Server-SideorClient-Side

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

Prompt your user to retry connecting their Item in a few hours, or the following day.

Check the status of the institution via the Dashboard or /institutions/get_by_id.

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.

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

INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT

Institution not enabled in this environment

Server-Side

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

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

INSTITUTION_NOT_FOUND

This institution was not found. Please check the ID supplied

Server-Side

Common causes

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

Troubleshooting steps

Check that the institution_id being used is correct.

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

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.

Server-SideorClient-Side

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.
A new Plaid developer is attempting to connect to Bank of America in Production or Development. Access to Bank of America in Development is currently unavailable for developer accounts that have not yet been approved for Production, and access to Bank of America for new developer accounts in Production is temporarily delayed until several days after Production access has been approved. If you require immediate access to Bank of America, contact Support.

Troubleshooting steps

Prompt your user to retry connecting their Item in a few hours, or the following day.

Check the status of the institution via the Dashboard or Institutions API.

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.

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

INSTITUTION_NOT_AVAILABLE

The financial institution is not available this time.

Server-SideorClient-Side

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

Prompt your user to retry connecting their Item in a few hours or the following day.

Check the status of the institution via the Dashboard or API.

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.

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

INSTITUTION_NO_LONGER_SUPPORTED

Plaid no longer supports this financial institution.

Server-SideorClient-Side

Common causes

The financial institution is no longer supported on Plaid's platform.
A new Plaid developer is attempting to connect to Bank of America in Production or Development. Access to Bank of America in Development is currently unavailable for developer accounts that have not yet been approved for Production, and access to Bank of America for new developer accounts in Production is temporarily delayed until several days after Production access has been approved. If you require immediate access to Bank of America, contact Support.
The institution has switched from supporting non-OAuth-based connections to requiring OAuth-based connections.

If the affected institution is Bank of America, apply for Production access via the Plaid dashboard.

If the affected institution is Capital One, refer to the migration guide provided by Plaid via email for migration instructions. If you are unable to find your migration guide, contact Support.

For other institutions, this error is un-retryable and requires custom updates from Plaid to resolve. Submit a Support ticket with the failing institution_id for more detailed information.

API error response
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_NO_LONGER_SUPPORTED",
 "error_message": "this institution is no longer supported",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

UNAUTHORIZED_INSTITUTION

You are not authorized to create Items for this institution at this time.

Server-Side

Common causes

Access to this institution is subject to additional verification and must be manually enabled for your account.

Troubleshooting steps

Make sure your account is enabled for Production access.

Contact your Plaid Account Manager or Plaid Support for details about how to access this institution.

API error response
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "UNAUTHORIZED_INSTITUTION",
 "error_message": "not authorized to create items for this institution",
 "display_message": "You are not authorized to create items for this institution at this time.",
 "request_id": "HNTDNrA8F1shFEW"
}

INSTITUTION_REGISTRATION_REQUIRED

Your application is not yet registered with the institution.

Server-Side

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

If your account was recently enabled for Production access, please allow up to a week for registration to be completed with the institution.

If your account was enabled for Production access over a week ago, please contact Support regarding the status of your registration.

API error response
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INSTITUTION_ERROR",
 "error_code": "INSTITUTION_REGISTRATION_REQUIRED",
 "error_message": "not yet registered to create items for this institution",
 "display_message": "You must register your application with this institution before you can create items for it.",
 "request_id": "HNTDNrA8F1shFEW"
}