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:
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.
PRODUCT_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.
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`.
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.
Asset Report errors:
PRODUCT_NOT_ENABLED
This means you’ll need to contact Plaid about enabling your client_id for this product.
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.
Retryable
Rate limit exceeded:
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)
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 in response to API calls:
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
"AUTH_LIMIT"
"IDENTITY_LIMIT"
"ITEM_GET_LIMIT"
"RATE_LIMIT"
"TRANSACTIONS_LIMIT"
API errors
"INTERNAL_SERVER_ERROR"
"PLANNED_MAINTENANCE"
Asset Report 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"