This article is a breakdown of Plaid error codes and our recommendations for how to best handle them.
Requires Client Action
Invalid request errors:
Client sends a malformed request that is missing fields. Please verify that your request body is properly formatted. If the
INVALID_REQUEST error is unclear, please refer directly to the Plaid documentation or check out the Plaid Postman Collection for request bodies that you can modify yourself to verify within your own Plaid environment.
Invalid input errors:
Client sends the correct fields but invalid data. Similarly with Invalid request errors, please verify that your request body contains valid Plaid identifiers or access to specific Plaid products. The Plaid documentation details how invalid fields may throw an
INVALID_INPUT error type.
Link was initialized in update mode for an Item that is in a good state. No further action is required. Double check the logic for when you prompt users to reconnect via update mode.
POST /auth/get when there are no valid checking or savings account(s) for which account and routing numbers are provided. Client should prompt end user to connect a different account for `auth`.
POST /liabilities/get when there are no valid liability account(s) for which liabilities could be retrieved.
Returned when a
POST request is made for a product whose data pull has not yet finished. Please use webhooks to determine when to fetch new data.
Returned when a data request has been made for an Item for a product that it does not support. Use the
/item/get endpoint to find out which products an Item supports.
Asset Report errors and warnings:
This means you’ll need to contact Plaid about enabling your
client_id for this product.
You tried to retrieve an Asset Report with Insights but you do not have access to this feature. Please contact us for more information.
You tried to retrieve an Asset Report with Insights and you do have access to the feature, but you did not have permission to create an Asset Report with Insights at the time of Asset Report creation. To retrieve this Asset Report as an Asset Report with Insights, you will need to recreate the Asset Report.
Plaid was not able to pull account information due to the included
Plaid can no longer provide support for this Item, please prompt your user to connect a different account.
Requires End User Action
The username provided in update mode via Link did not match the original username for the Item. You should prompt your user to connect a new account if they have indeed changed their username.
Your user entered invalid credentials in Link and should retry.
Launch Link in update mode to enable your user to repair their connection.
Your user must contact their bank or log into their online banking portal to resolve.
ITEM_NOT_SUPPORTED, MFA_NOT_SUPPORTED, NO_ACCOUNTS, NO_AUTH_ACCOUNTS
Your user should link a different account because the account they have attempted to link is not supported.
The user did not provide sufficient authorization in order to link their account via an OAuth login flow.
Plaid uses dynamic rate limits to halt abuse of the Plaid API and to prevent fraud. Clients should limit the number of times they call any Plaid API endpoint for a specific
access_token. If your user is encountering a rate limit exceeded error when trying to link their account, we recommend your user retries the following day.
Internal server error:
In general, these errors occur due to an unrecognized response from a financial institution which frequently corresponds to institution downtime. It’s reasonable to retry these errors a few hours after failure.
Asset report errors:
causes field will have more detailed information, such as institution down.
Likely due to temporary downtime – please prompt your user to retry later.
INSTITUTION_DOWN, INSTITUTION_NOT_RESPONDING, INSTITUTION_NOT_AVAILABLE
These errors correspond to different types of institution downtime. In general, retrying the following day should be successful. If the problem persists, please reach out to Plaid Support.
When to Expect Errors
This section outlines specific flows where a Plaid error might occur. Note that errors which occur during the Plaid Link flow are received via the
Occurs during initial Item add:
Invalid input errors
Rate limit errors
"RATE_LIMIT"(this can occur if your user unsuccessfully enters their credentials repeatedly)
Occurs during Link update mode:
Invalid input errors
Occurs during Link verify mode
Occurs in response to API calls:
Invalid request errors
Invalid input errors
Rate limit exceeded errors
The following rate limits can occur if you make too many API requests to specific product endpoints:
Asset Report errors
These errors can only occur if you are using the Assets endpoints: