API Errors

Guide to troubleshooting API errors

INTERNAL_SERVER_ERROR or plaid-internal-error

Plaid was unable to process the request
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 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.
Troubleshooting steps

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.

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

PLANNED_MAINTENANCE

Plaid's systems are undergoing maintenance and API operations are disabled
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 systems are under maintenance and API operations are temporarily disabled. Advance notice will be provided when a maintenance window is planned.
Troubleshooting steps

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

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