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.
Item errors:
ITEM_NO_ERROR
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.
NO_AUTH_ACCOUNTS
Returned from 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`.
NO_INVESTMENT_ACCOUNTS
Returned from POST /investments/holdings/get or POST /investments/transactions/get when there are no valid investment account(s) for which holdings or transactions could be retrieved.
NO_LIABILITY_ACCOUNTS
Returned from POST /liabilities/get when there are no valid liability account(s) for which liabilities could be retrieved.
PRODUCT_NOT_READY
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.
PRODUCTS_NOT_SUPPORTED
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:
PRODUCT_NOT_ENABLED
This means you’ll need to contact Plaid about enabling your client_id for this product.
INSIGHTS_NOT_ENABLED
You tried to retrieve an Asset Report with Insights but you do not have access to this feature. Please contact us for more information.
INSIGHTS_PREVIOUSLY_NOT_ENABLED
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.
OWNERS_UNAVAILABLE
Plaid was not able to pull account information due to the included Cause.
Institution errors:
INSTITUTION_NO_LONGER_SUPPORTED
Plaid can no longer provide support for this Item, please prompt your user to connect a different account.
Requires End User Action
INVALID_UPDATED_USERNAME
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.
INVALID_CREDENTIALS, INVALID_MFA
Your user entered invalid credentials in Link and should retry.
ITEM_LOGIN_REQUIRED
Launch Link in update mode to enable your user to repair their connection.
ITEM_LOCKED, USER_SETUP_REQUIRED
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.
INSUFFICIENT_CREDENTIALS
The user did not provide sufficient authorization in order to link their account via an OAuth login flow.
Retryable
Rate limits:
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:
DATA_UNAVAILABLE
The causes field will have more detailed information, such as institution down.
ASSET_REPORT_GENERATION_FAILED
Likely due to temporary downtime – please prompt your user to retry later.
Institution errors:
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 onExit callback.
Occurs during initial Item add:
Item errors
"INVALID_CREDENTIALS"
"INVALID_MFA"
"ITEM_LOCKED"
"ITEM_NOT_SUPPORTED"
"MFA_NOT_SUPPORTED"
"NO_ACCOUNTS"
"USER_SETUP_REQUIRED"
Invalid input errors
"INVALID_PUBLIC_TOKEN"
Institution errors
"INSTITUTION_DOWN"
"INSTITUTION_NOT_AVAILABLE"
"INSTITUTION_NOT_RESPONDING"
"INSTITUTION_NO_LONGER_SUPPORTED"
Rate limit errors
"RATE_LIMIT"(this can occur if your user unsuccessfully enters their credentials repeatedly)
"ADDITION_LIMIT" (you have exceeded your live credential limit in the Development environment - to increase it please contact Plaid Support, or migrate to Production)
Occurs during Link update mode:
Item errors
"INVALID_CREDENTIALS"
"INVALID_MFA"
"INVALID_UPDATED_USERNAME"
"ITEM_LOCKED"
"ITEM_NOT_SUPPORTED"
"ITEM_NO_ERROR"
"MFA_NOT_SUPPORTED"
"NO_ACCOUNTS"
"USER_SETUP_REQUIRED"
Invalid input errors
"INVALID_PUBLIC_TOKEN"
Institution errors
"INSTITUTION_DOWN"
"INSTITUTION_NOT_AVAILABLE"
"INSTITUTION_NOT_RESPONDING"
"INSTITUTION_NO_LONGER_SUPPORTED"
Occurs during Link verify mode
"INCORRECT_DEPOSIT_AMOUNTS"
"TOO_MANY_VERIFICATION_ATTEMPTS"
Occurs in response to API calls:
Auth errors
"VERIFICATION_EXPIRED"
Item errors
"NO_AUTH_ACCOUNTS"
"PRODUCTS_NOT_SUPPORTED"
"PRODUCT_NOT_READY"
“ITEM_LOGIN_REQUIRED”
Invalid request errors
"INVALID_BODY"
"INVALID_FIELD"
"INVALID_HEADERS"
"MISSING_FIELDS"
"NOT_FOUND"
"SANDBOX_ONLY"
"UNKNOWN_FIELDS"
Invalid input errors
"INVALID_ACCESS_TOKEN"
"INVALID_ACCOUNT_ID"
"INVALID_API_KEYS"
"INVALID_INSTITUTION"
"INVALID_PRODUCT"
"INVALID_PUBLIC_TOKEN"
"UNAUTHORIZED_ENVIRONMENT"
Rate limit exceeded errors
The following rate limits can occur if you make too many API requests to specific product endpoints:
"ACCOUNTS_LIMIT"
"AUTH_LIMIT"
"IDENTITY_LIMIT"
"INCOME_LIMIT"
"ITEM_GET_LIMIT"
"TRANSACTIONS_LIMIT"
API errors
"INTERNAL_SERVER_ERROR"
"PLANNED_MAINTENANCE"
Asset Report errors
These errors can only occur if you are using the Assets endpoints:
"ASSET_REPORT_GENERATION_FAILED"
"DATA_UNAVAILABLE"
"INVALID_PARENT"
"PRODUCT_NOT_ENABLED"
"PRODUCT_NOT_READY"
Institution errors
"INSTITUTION_DOWN"
"INSTITUTION_NOT_AVAILABLE"
"INSTITUTION_NOT_RESPONDING"
"INSTITUTION_NO_LONGER_SUPPORTED"