API Errors

Guide to troubleshooting API errors

INTERNAL_SERVER_ERROR or plaid-internal-error

Plaid was unable to process the request

Sample user-facing error message

Something went wrong: There was a problem and we couldn't connect your account. Try entering your username and password again.

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 received an unsupported response from a financial institution, which frequently corresponds to an institution error.
Plaid is experiencing internal system issues.
A product endpoint request was made for an Item at an OAuth-based institution, but the end user did not authorize the Item for the specific product, or has revoked Plaid's access to the product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account.

Retry the request. If the endpoint supports the use of an idempotency key parameter, ensure you are using one before retrying. If the endpoint is /transfer/create, see Handling errors in transfer creation.

If the Item is at an OAuth-based institution, prompt the end user to allow Plaid to access identity data and/or account and routing number data. The end user should do this during the Link flow if they were unable to successfully complete the Link flow for the Item, or at their institution's online banking portal if the Item has already been added.

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 Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

API error response
1http code 500
2{
3 "error_type": "API_ERROR",
4 "error_code": "INTERNAL_SERVER_ERROR",
5 "error_message": "an unexpected error occurred",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

PLANNED_MAINTENANCE

Plaid's systems are undergoing maintenance and API operations are disabled

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

Plaid's systems are under maintenance and API operations are temporarily disabled. Advance notice will be provided when a maintenance window is planned.

Troubleshooting steps

Check Plaid's System status for any recent maintenance updates.

If you have not been previously informed of planned maintenance, please reach out to Plaid Support for more information.

API error response
1http code 503
2{
3 "error_type": "API_ERROR",
4 "error_code": "PLANNED_MAINTENANCE",
5 "error_message": "the Plaid API is temporarily unavailable due to planned maintenance. visit https://status.plaid.com/ for more information",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}