Invalid Input Errors

Guide to troubleshooting invalid input errors

DIRECT_INTEGRATION_NOT_ENABLED

An attempt was made to create an Item without using Link.

Common causes

/item/create was called directly, without using Link.

Troubleshooting steps

In the Development or Production environments, use Link to create the Item. In Sandbox, use /sandbox/public_token/create

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "DIRECT_INTEGRATION_NOT_ENABLED",
5 "error_message": "your client ID is only authorized to use Plaid Link. head to the docs (https://plaid.com/docs) to get started.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INCORRECT_DEPOSIT_VERIFICATION

The user submitted an incorrect Manual Same-Day micro-deposit verification input during Item verification in Link.

User-facing error message

Code is incorrect, 2 attempts remaining: Check the bank statement of your account ending in •••0000 for the <b>$0.01 deposit</b> and try again.

Common causes

Your user submitted an incorrect micro-deposit verification input when verifying an account via Manual Same-Day micro-deposits.

Troubleshooting steps

Have your user attempt to enter the micro-deposit verification input again.

If your user enters an incorrect micro-deposit verification input three times, the Item will be permanently locked. In this case, you must restart the Link flow from the beginning and have the user re-link their account.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INCORRECT_DEPOSIT_VERIFICATION",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INCORRECT_DEPOSIT_AMOUNTS

This error code has been deprecated. This will only be used for Manual Same-Day micro-deposits customers before January 23, 2023.

The user submitted incorrect Manual Same-Day micro-deposit amounts during Item verification in Link.

User-facing error message

Amounts were incorrect, 2 attempts remaining: Check the account statement of your account ending in 0000 for the two small deposits and try again

Common causes

Your user submitted incorrect micro-deposit amounts when verifying an account via Manual Same-Day micro-deposits.

Troubleshooting steps

Have your user attempt to enter the micro-deposit amounts again.

If your user has entered incorrect micro-deposit amounts three times, the Item will be permanently locked. In this case, you must restart the Link flow from the beginning and have the user re-link their account.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INCORRECT_DEPOSIT_AMOUNTS",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_ACCESS_TOKEN

Common causes

Access tokens are in the format: access-<environment>-<identifier>
This error can happen when the access_token you provided is invalid or pertains to a different API environment

Troubleshooting steps

Make sure you are not using a token created in one environment in a different environment (for example, using a Sandbox token in the Development environment).

Ensure that the client_id, secret, and access_token are all associated with the same Plaid developer account.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_ACCESS_TOKEN",
5 "error_message": "could not find matching access token",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_ACCOUNT_ID

The supplied `account_id` is not valid

Common causes

One of the account_id(s) specified in the API call's account_ids object is invalid or does not exist.

Your integration is passing a correctly formatted, but invalid account_id for the Item in question.
The underlying account may have been closed at the bank, and thus removed from our API.
The Item affected is at an institution that uses OAuth-based connections, and the user revoked access to the specific account.
The account_id was erroneously removed from our API, either completely or a new account_id was assigned to the same underlying account.
You are requesting an account that your user has de-selected in the Account Select v2 update flow.

Troubleshooting steps

Verify that your integration is passing in correctly formatted and valid account_id(s)

Ensure that your integration only uses account_id(s) that belong to the Item in question. Early on in your development it is important to verify that your integration only uses account_id(s), and other Plaid identifiers like item_id, for the Item that they belong to.

Also be sure to preserve the case of any non-numeric characters in Plaid identifiers, as they are case sensitive.

Verify the Item's currently active accounts and their account_id(s).

The user may have revoked access to the account. If this is the case, it is a security best practice to give the user a choice between restoring their account and having your app delete all data for that account. If your user wants to restore access to the account, you can put them through update mode, which will give them the option to grant access to the account again. Note that doing so will result in an account with a new and different account_id, which can be obtained by calling /accounts/get.

Verify that after completing update mode, your implementation checks for the current account_id information associated with the Item, instead of re-using the pre-update mode account_id(s). Updated account_id data can be found in the onSuccess Link event, or by calling certain endpoints, such as /accounts/get.

Verify that the account_id was not changed or removed from the API.

If the underlying account has not been closed or changed at the bank and the account_id no longer appears, Plaid may have removed the account entirely or assigned the account a new account_id, a situation known as "account churn".

Some common causes for account churn are:

The Item was in an unhealthy state for an extended period of time. If an Item has remained in an error state for over a year, its underlying data may be removed. If the Item is then later refreshed, the Item data will be re-generated, resulting in new account_id data.
The bank or user drastically changing the name of the account, e.g. an account named "Savings account" becomes "Jane's vacation fund".
The account's mask is changed by the bank, which can occur when banks change their backend systems.

Account churn caused by the latter two reasons is unexpected API behavior. If you experience account churn on an Item that was otherwise healthy, file a Support ticket.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_ACCOUNT_ID",
5 "error_message": "failed to find requested account ID for requested item",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_API_KEYS

The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard.

Common causes

The API keys are not valid for the environment being used, which can commonly happen when switching between development environments and forgetting to switch API keys

Troubleshooting steps

Find your API keys in the Dashboard.

Make sure you are using the secret that corresponds to the environment you are using (Sandbox, Development, or Production).

Make sure you are not using a token created in one environment in a different environment (for example, using a Sandbox token in the Development environment).

Visit the Plaid Dashboard to verify that you are enabled for the environment you are using.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_API_KEYS",
5 "error_message": "invalid client_id or secret provided",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_AUDIT_COPY_TOKEN

The audit copy token supplied to the server was invalid.

Common causes

You attempted to access an Asset Report using an audit_copy_token that is invalid or was revoked using /asset_report/audit_copy/remove or /asset_report/remove.

Troubleshooting steps

Generate a new audit_copy_token via /asset_report/audit_copy/create.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_AUDIT_COPY_TOKEN",
5 "error_message": null,
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_INSTITUTION

The `institution_id` specified is invalid or does not exist.

Common causes

The institution_id specified is invalid or does not exist.

Troubleshooting steps

Check the institution_id to ensure it is valid.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_INSTITUTION",
5 "error_message": "invalid institution_id provided",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_LINK_CUSTOMIZATION

The Link customization is not valid for the request.

Common causes

This error can happen when requesting to update account selections with a Link customization that does not enable Account Select v2.

Troubleshooting steps

Update your Link customization to enable Account Select v2 or use a Link customization with Account Select v2 enabled.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_LINK_CUSTOMIZATION",
5 "error_message": "requested link customization is not set to update account selection",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_LINK_TOKEN

The `link_token` provided to initialize Link was invalid.

User-facing error message

Username or password incorrect: Check that your credentials are the same that you use for this institution

Common causes

The link_token has expired. A link_token lasts at least 30 minutes before expiring.
The link_token was already used. A link_token can only be used once, except when working in the Sandbox test environment.
The link_token was created in a different environment than the one it was used with. For example, a Sandbox link_token was used in Production.
A user entered invalid credentials too many times during the Link flow, invalidating the link_token.

Troubleshooting steps

Confirm that the link_token is from the correct environment.

Generate a new link_token for initializing Link with and re-launch Link.

For more detailed instructions on handling this error, see Handling invalid Link Tokens.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_LINK_TOKEN",
5 "error_message": "invalid link_token provided",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_PROCESSOR_TOKEN

The `processor_token` provided to initialize Link was invalid.

Common causes

The processor_token used to initialize Link was invalid.

Troubleshooting steps

If you are testing in Sandbox, make sure that your processor_token was created using the Sandbox-specific endpoint /sandbox/processor_token/create instead of /processor_token/create. Likewise, if testing in Development or Production, make sure that your processor_token was created using /processor_token/create rather than /sandbox/processor_token/create.

Make sure you are not using a processor_token created in one environment in a different environment (for example, using a Sandbox token in the Development environment).

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PROCESSOR_TOKEN",
5 "error_message": null,
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_PRODUCT

Your client ID does not have access to this product.

Common causes

The endpoint you are trying to access must either be manually enabled for your account or requires a different pricing plan.
Your integration is using a partner endpoint integration that has not yet been enabled in the Dashboard.
Your integration is attempting to call a processor endpoint on an Item that was initialized with products that are not compatible with processor endpoints.

Troubleshooting steps

If you are using a partner integration, check the Dashboard Integrations page to make sure it is enabled.

Update the products parameter in the /link/token/create call to remove any products other than auth or identity, and make sure that you are not using endpoints for products other than Balance, Auth, or Identity with this Item.

Contact Sales to gain access.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PRODUCT",
5 "error_message": "products must either be null or a list of strings containing at least one valid product",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_PRODUCTS

The pre-authenticated returning user flow was initiated with a restricted product.

User-facing error message

Something went wrong: There was a problem and we couldn't connect your account. Try entering your username and password again.

Common causes

For a returning user, Link was initiated with a product that is restricted from the pre-authenticated returning user flow.

Troubleshooting steps

Either re-initiate the Link flow without the restricted product, or contact your Plaid Account Manager or file a Support request to disable the pre-authenticated flow for your integration.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PRODUCTS",
5 "error_message": "The following products are not allowed for pre-authed items: ['auth'].",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

ADDITIONAL_CONSENT_REQUIRED

The end user has not provided consent to the requested product

Common causes

You have migrated to Data Transparency Messaging and are trying to access an endpoint you did not collect consent for.

Troubleshooting steps

If you have migrated to Data Transparency Messaging, check that the products or additional_consented_products parameters passed to /link/token/create include the product you are requesting. You can fix any Items with missing consent by using update mode.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "ADDITIONAL_CONSENT_REQUIRED",
5 "error_message": "client does not have user consent to access the PRODUCT_AUTH product",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_PUBLIC_TOKEN

Common causes

Public tokens are in the format: public-<environment>-<identifier>
This error can happen when the public_token you provided is invalid, pertains to a different API environment, or has expired.

Troubleshooting steps

Make sure you are not using a token created in one environment in a different environment (for example, using a Sandbox token in the Development environment).

Ensure that the client_id, secret, and public_token are all associated with the same Plaid developer account.

The public_token expires after 30 minutes. If your public_token has expired, send your user to the Link flow to generate a new public_token.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_PUBLIC_TOKEN",
5 "error_message": "could not find matching public token",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_STRIPE_ACCOUNT

The supplied Stripe account is invalid

Common causes

After /processor/stripe/bank_account_token/create was called, Plaid received a response from Stripe indicating that the Stripe account specified in the API call's account_id is invalid.

Troubleshooting steps

See the returned error_message, which contains information from Stripe regarding why the account was deemed invalid.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_STRIPE_ACCOUNT",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_USER_TOKEN

The supplied user token is invalid

Common causes

The user token is not associated with the given user ID.
The user token is invalid or pertains to a different API environment.

Troubleshooting steps

Check that the user token is entered correctly.

Make a call to /user/create to create a user token for the given user ID.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_USER_TOKEN",
5 "error_message": "could not find matching user token",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_WEBHOOK_VERIFICATION_KEY_ID

The `key_id` provided to the webhook verification endpoint was invalid.

Common causes

A request was made to /webhook_verification_key/get using an invalid key_id.
The call to /webhook_verification_key/get was made from an environment different than the one the webhook was sent from (for example, verification of a Sandbox webhook was attempted against Production).

Troubleshooting steps

Ensure that the key_id argument provided to /webhook_verification_key/get is in fact the kid extracted from the JWT headers. See webhook verification for detailed instructions.

Ensure that the webhook is being verified against the same environment as it originated from.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "INVALID_WEBHOOK_VERIFICATION_KEY_ID",
5 "error_message": "invalid key_id provided. note that key_ids are specific to Plaid environments, and verification requests must be made to the same environment that the webhook was sent from",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

PRODUCT_UNAVAILABLE

Additional products may not be added to Items created in the pre-auth returning user flow.

Common causes

A request was made to an Item created via the pre-authenticated returning user flow for a product that the Item was not initialized with during the original Link flow.

Troubleshooting steps

If using the pre-authenticated returning user flow, make sure to provide all the products you will be using in the products array at Link initialization.

If you need to use a product that is not supported by the pre-authenticated returning user flow, e.g. auth, contact your Plaid Account Manager to disable the pre-authenticated returning user flow for your integration.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "PRODUCT_UNAVAILABLE",
5 "error_message": "Additional products may not be added to this pre-authed item.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

TOO_MANY_VERIFICATION_ATTEMPTS

The user attempted to verify their Manual Same-Day micro-deposit amounts more than 3 times and their Item is now permanently locked. The user must retry submitting their account information in Link.

User-facing error message

No attempts remaining: You’ve used up all of your attempts. To continue, connect a different bank

Common causes

Your user repeatedly submitted incorrect micro-deposit amounts when verifying an account via Manual Same-Day micro-deposits.

Troubleshooting steps

Re-initiate the Link flow and have your user attempt to verify their account again.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "TOO_MANY_VERIFICATION_ATTEMPTS",
5 "error_message": "",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

UNAUTHORIZED_ENVIRONMENT

Your client ID does not have access to this API environment. See which environments you are enabled for from the Dashboard.

User-facing error message

Unauthorized environment: Your Client ID is not authorized to access this API environment. Contact Support to gain access

Common causes

You may not be enabled for the environment you are using.
Your code may be calling a deprecated endpoint.

Troubleshooting steps

Visit the Plaid Dashboard to verify that you are enabled for the environment you are using.

Make sure that your code is not calling deprecated endpoints. Actively supported endpoints are listed in the API reference.

Find your API keys in the Dashboard.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "UNAUTHORIZED_ENVIRONMENT",
5 "error_message": "you are not authorized to create items in this api environment. Go to the Dashboard (https://dashboard.plaid.com) to see which environments you are authorized for.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

UNAUTHORIZED_ROUTE_ACCESS

Your client ID does not have access to this route.

Common causes

The endpoint you are trying to access must be manually enabled for your account.

Troubleshooting steps

Contact Sales to gain access.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "UNAUTHORIZED_ROUTE_ACCESS",
5 "error_message": "you are not authorized to access this route in this api environment.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

USER_PERMISSION_REVOKED

The end user has revoked access to their data.

Common causes

The end user revoked access to their data via the Plaid consumer portal at my.plaid.com.

Troubleshooting steps

Delete the item using /item/remove and prompt your user to re-enter the Link flow to re-authorize access to their data. Note that if the user re-authorizes access, a new Item will be created, and the old Item will not be re-activated.

If applicable, direct your user to a fallback, manual flow for gathering account data.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_INPUT",
4 "error_code": "USER_PERMISSION_REVOKED",
5 "error_message": "the holder of this account has revoked their permission for your application to access it",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Invalid Input Errors

Guide to troubleshooting invalid input errors

DIRECT_INTEGRATION_NOT_ENABLED

An attempt was made to create an Item without using Link.

Common causes

Troubleshooting steps

Was this helpful?

INCORRECT_DEPOSIT_VERIFICATION

The user submitted an incorrect Manual Same-Day micro-deposit verification input during Item verification in Link.

User-facing error message

Common causes

Troubleshooting steps

Was this helpful?

INCORRECT_DEPOSIT_AMOUNTS

The user submitted incorrect Manual Same-Day micro-deposit amounts during Item verification in Link.

User-facing error message

Common causes

Troubleshooting steps

Was this helpful?

INVALID_ACCESS_TOKEN

Common causes

Troubleshooting steps

Was this helpful?

INVALID_ACCOUNT_ID

The supplied account_id is not valid

Common causes

Troubleshooting steps

Was this helpful?

INVALID_API_KEYS

The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard.

Common causes

Troubleshooting steps

Was this helpful?

INVALID_AUDIT_COPY_TOKEN

The audit copy token supplied to the server was invalid.

Common causes

Troubleshooting steps

Was this helpful?

INVALID_INSTITUTION

The institution_id specified is invalid or does not exist.

Common causes

Troubleshooting steps

Was this helpful?

INVALID_LINK_CUSTOMIZATION

The Link customization is not valid for the request.

Common causes

Troubleshooting steps

Was this helpful?

INVALID_LINK_TOKEN

The link_token provided to initialize Link was invalid.

User-facing error message

Common causes

Troubleshooting steps

Was this helpful?

INVALID_PROCESSOR_TOKEN

The processor_token provided to initialize Link was invalid.

Common causes

Troubleshooting steps

Was this helpful?

INVALID_PRODUCT

Your client ID does not have access to this product.

Common causes

Troubleshooting steps

Was this helpful?

INVALID_PRODUCTS

The pre-authenticated returning user flow was initiated with a restricted product.

User-facing error message

Common causes

Troubleshooting steps

Was this helpful?

ADDITIONAL_CONSENT_REQUIRED

The end user has not provided consent to the requested product

Common causes

Troubleshooting steps

Was this helpful?

INVALID_PUBLIC_TOKEN

Common causes

Troubleshooting steps

Was this helpful?

INVALID_STRIPE_ACCOUNT

The supplied `account_id` is not valid

The `institution_id` specified is invalid or does not exist.

The `link_token` provided to initialize Link was invalid.

The `processor_token` provided to initialize Link was invalid.

The `key_id` provided to the webhook verification endpoint was invalid.