Errors
A comprehensive breakdown of all Plaid error codes
Most common errors
The following are the most common errors that may occur in response to an API call even if your implementation is correct. This list of common errors excludes Item errors that occur only during the Link flow (typically due to bad data entry by the end user), such as INVALID_CREDENTIALS, and errors that can occur only due to sending invalid input, such as INVALID_FIELD. It is recommended that your integration should, at minimum, handle each of the errors below that are applicable to your product and/or integration mode.
In the table below, "Item-based products" refers to any product or integration that uses an access token; it excludes products such as Identity Verification, Enrich, and Document Income that do not maintain a connection to a financial institution.
| Error | Applies to | Summary |
|---|---|---|
ITEM_LOGIN_REQUIRED | All Item-based products | Item has expired credentials or consent |
PRODUCT_NOT_READY | Signal, Assets, Income, Check, Auth, /transactions/get | Plaid hasn't finished obtaining the data needed to fulfill your request |
PRODUCTS_NOT_SUPPORTED | All Item-based products | The product endpoint isn't compatible with this Item |
TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION | /transactions/sync | An update was received during Transactions pagination |
NO_ACCOUNTS | All Item-based products | Couldn't find any open accounts |
NO_AUTH_ACCOUNTS | Auth | Couldn't find any debitable checking or savings accounts |
NO_LIABILITY_ACCOUNTS | Liabilities | Couldn't find any credit accounts |
NO_INVESTMENT_ACCOUNTS | Investments | Couldn't find any investment accounts |
ACCESS_NOT_GRANTED | All Item-based products | The end user didn't grant an OAuth permission required for your request |
ADDITIONAL_CONSENT_REQUIRED | Integrations in the US or Canada that add products to Items after Link | The end user didn't grant a data scope required for your request |
INSTITUTION_NOT_RESPONDING | All Item-based products | Temporary financial institution connectivity outage |
INSTITUTION_DOWN | All Item-based products | Temporary financial institution connectivity outage |
RATE_LIMIT_EXCEEDED | Applications that batch-process Plaid API calls or have heavy traffic spikes | Too many requests made too quickly, or Limited Production caps hit |
INTERNAL_SERVER_ERROR | All products | Internal error or financial institution error not otherwise specified |
Errors overview
Item errors Occur when an Item may be invalid or not supported on Plaid's platform. | NO_AUTH_ACCOUNTS or no-depository-accounts |
Institution errors Occur when there are errors for the requested financial institution. | |
API errors Occur during planned maintenance and in response to API errors. | INTERNAL_SERVER_ERROR or plaid-internal-error |
Assets errors Occur for errors related to Asset endpoints. | |
Payment errors Occur for errors related to Payment Initiation endpoints. | |
Virtual Account errors Occur for errors related to Virtual Account endpoints. | |
Transactions errors Occur for errors related to Transactions endpoints. | |
Transfer errors Occur for errors related to Transfer endpoints. | |
Income errors Occur for errors related to Income endpoints. | |
Sandbox errors Occur when invalid parameters are supplied in the Sandbox environment. | |
Invalid Request errors Occur when a request is malformed and cannot be processed. | |
Invalid Input errors Occur when all fields are provided, but the values provided are incorrect in some way. | |
Invalid Result errors Occur when a request is valid, but the output would be unusable for any supported flow. | |
Rate Limit Exceeded errors Occur when an excessive number of requests are made in a short period of time. | |
ReCAPTCHA errors Occur when a ReCAPTCHA challenge has been presented or failed during the link process. | |
OAuth errors Occur when there is an error in OAuth authentication. | |
Micro-deposits errors Occur when there is an error with micro-deposits. | |
Partner errors Occur when there is an error with creating or managing end customers. | |
Error schema
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_typeINVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERRORerror_codeerror_code_reasonnull will be returned otherwise. Safe for programmatic use.Possible values:
OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.OAUTH_REVOKED_TOKEN: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_messagedisplay_messagenull if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_idcausescauses will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.statusdocumentation_urlsuggested_action