Errors (2024)

Sample user-facing error message

Insufficient Sharing Permissions

:

There was an error connecting to your account. Try linking your account again by selecting the required information to share with this application.

• This Item's access is affected by institution-hosted access controls.
• The user did not agree to share, or has revoked, access to the data required for the requested product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account.
• The user does not have permission to share required information about the account. This can happen at some institutions using OAuth connections if the user is not the account owner (for example, they have a role such as trustee, investment advisor, power of attorney holder, or authorized cardholder).

Prompt the end user to allow Plaid to access identity data and/or account and routing number data. The end user should do this during the Link flow if they were unable to successfully complete the Link flow for the Item, or via Link’s update mode if the Item has already been added.

If the error occurred after attempting to add Auth or Identity to a previously healthy Item, send the user through Update Mode with Product Validations to allow them to share the required information.

If your Plaid integration involves adding products to Items after Link (instead of specifying these products in the /link/token/create products array) consider using Required if Supported Products instead. This will ensure that your user has selected the required permissions for these additional products during Link, reducing the frequency with which ACCESS_NOT_GRANTED errors will occur.

If there are other security settings on the user's account that prevent sharing data with aggregators, they should adjust their security preferences on their institution's online banking portal. It may take up to 48 hours for changes to take effect.

Confirm that the user is the owner of the account.

• Instant Auth could not be used for the Item, and Instant Match has been enabled for your account, but a country other than US is specified in Link's country code initialization.
• The Item does not support Instant Auth or Instant Match. If this is the case, Plaid will automatically attempt to enter a micro-deposit based verification flow.

Update the countries used to initialize Link. Instant Match can only be used when Link is initialized with US as the only country code.

Review Link activity logs to verify whether a micro-deposit verification flow was launched in Link after this error occurred. If it was not launched, see Add institution coverage for more information on enabling micro-deposit verification flows. If it was launched successfully, no further troubleshooting action is required.

Sample user-facing error message

Access Denied

:

The authorization flow did not complete

• Your user abandoned the bank OAuth flow without completing it.

Have your user attempt to link their account again.

If this error persists, please submit aSupport ticket with the followingidentifiers: access_token, institution_id, and either link_session_id orrequest_id.

Sample user-facing error message

The credentials you provided were incorrect

:

Check that your credentials are the same that you use for this institution

Your user will be redirected to the Credentials pane to retry entering correct credentials.

• The user entered incorrect credentials at their selected institution.
  • Extra spaces, capitalization, and punctuation errors are common causes of INVALID_CREDENTIALS.
• The institution requires special configuration steps before the user can link their account with Plaid. KeyBank, Interactive Brokers, and Betterment are examples of institutions that require this setup.
• The user selected the wrong institution.
  • Plaid supports institutions that have multiple login portals for the various products they offer, and it is common for users to confuse a different selection for the one which their credentials would actually be accepted.
  • This confusion is particularly common between Vanguard (brokerage accounts) and My Vanguard Plan (retirement accounts). This is also common for users attempting to link prepaid stored-value cards, as many institutions have separate login portals specifically for those cards.

Prompt your user to retry entering their credentials.

Note: The Institution may lock a user out of their account after 3-5 repeated attempts, resulting in an ITEM_LOCKED error.

Confirm that the credentials being entered are correct by asking the user to test logging in to their financial institution website using the same set of credentials.

The user should check their financial institution website for special settings to allow access for third-party apps, such as a "third party application password" or "allow third party access" setting.

Verify that the user is selecting the correct institution in Link’s Institution Select view.

If the credentials are confirmed to be legitimate, and a user still cannot authenticate, please submit an 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

Sample user-facing error message

The credentials you provided were incorrect

:

For security reasons, your account may be locked after several unsuccessful attempts

Your user will be redirected to the MFA pane to retry entering the correct value.

• The user entered an incorrect answer for the security question presented by the selected institution.
• The user selected an MFA device that is not active.
• The institution failed to send the one-time code for the user's selected device.

If the user still cannot log in despite providing correct information, or if they cannot receive an MFA token despite having the correct device, please submit a 'Invalid credentials errors' Support ticket with the following identifiers: institution_id, and either link_session_id or request_id.

Your user will be shown an error message indicating that an internal error occurred and will be prompted to close Link.

• The institution is experiencing login issues.
• The integration between Plaid and the financial institution is experiencing errors.

If the error persists, submit a 'Multi-factor authentication issues' Support ticket with the following identifiers: institution_id and either link_session_id or request_id.

Sample user-facing error message

Invalid Phone Number

:

We couldn't verify that 4151231234 is a valid number. Please re-enter your phone number to try again.

Your user will be redirected to the phone number input pane to retry submitting a valid phone number.

• The user entered an invalid phone number. Only US and CA phone numbers are accepted for the returning user experience.

If the user still cannot log in despite providing correct information, instruct the user to select "Maybe later" to continue in Link without the returning user experience.

Sample user-facing error message

Security code incorrect

:

Check that the code you entered is the same code that was sent to you

Your user will be redirected to the OTP input pane to retry submitting a valid OTP.

• The user entered an invalid OTP.

If the user still cannot log in despite providing correct information, instruct the user to select "Maybe later" to continue in Link without the returning user experience.

Sample user-facing error message

Error

:

Try entering your bank account username again. If you recently changed it, you may need to un-link your account and then re-link.

Your user will be directed to enter a different username.

• While linking an account in update mode, the user provided a username that doesn't match the original username provided when they originally linked the account.

If your user entered the wrong username, or the username for a different account, they should enter the correct, original username.

Have your user ensure that the capitalization for their username is the same as it was when they first logged in to Plaid. The username entered during update mode must case-match with the original username, even if the institution does not consider usernames case-sensitive.

If your user actually changed the username for the account, you should delete the original Item and direct your user to the regular Link flow to link their account as a new Item.

• An Item was deleted via /item/remove while a request for its data was in process.

If you plan to delete an Item immediately after retrieving data from it, make sure to wait until your request has successfully returned the data you need before calling /item/remove.

Sample user-facing error message

Too many attempts

:

Your account is locked for security reasons. Reset your bank username and password, and then try again.

Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account.

• The user entered their credentials incorrectly after more than 3-5 attempts, triggering the institution’s fraud protection systems and locking the user’s account.

Request that the user log in directly to their institution. Attempting to log in is a reliable way of confirming whether the user’s account is legitimately locked with a given institution. If the user cannot log in due to their account being locked, the website will usually note it as such, giving supplemental information on what they can do to resolve their account.

If the account is locked, ask the user to work with the financial institution to unlock their account.

Steps on unlocking an account are usually provided when a login attempt fails with the institution directly, in the event that their account is actually locked. Once unlocked, they should then try to re-authenticate using Plaid Link.

If the user is persistently locked out of their institution, submit an 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

Sample user-facing error message

Username or password incorrect

:

If you've recently updated your account with this institution, be sure you're entering your updated credentials

• The institution does not use an OAuth-based connection and the user changed their password.
• The institution does not use an OAuth-based connection and the user changed their multi-factor settings, or their multi-factor authentication has expired.
• The institution has undergone a migration from a non-OAuth-based connection to an OAuth-based connection.
• The institution uses an OAuth-based connection and the user's access-consent is no longer valid, either because it has expired, or because the user revoked access.
• The institution uses an OAuth-based connection that does not allow duplicate Items, but the user connected a duplicate Item to the same application.

Re-authenticate your user by implementing Link’s update mode and guide your user to fix their credentials or enter a new multi-factor token so Plaid can begin fetching data again.

If the Item is on an OAuth-based connection and has an expired consent_expiration_time, you may be able to reduce the frequency of this error by listening for the PENDING_EXPIRATION webhook and proactively sending the user through update mode before the Item expires.

If the Item is on an OAuth-based connection and the error was caused by the user adding a duplicate Item, remove the old Item, and see preventing duplicate Items for more details on preventing and remediating duplicate Items.

To recover from this error more quickly, listen for the LOGIN_REPAIRED webhook, which will fire when an Item exits ITEM_LOGIN_REQUIRED without going through update mode in your app.

If the error is legitimate, having the user authenticate again should generally return their Item to a healthy state without further intervention.

If this error persists, please submit a Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

• Item was previously removed via /item/remove.
• The user has depermissioned or deleted their Item via my.plaid.com.
• Plaid support has deleted the Item in response to a data deletion request from the user.

Launch a new instance of Plaid Link and prompt the user to create a new Item.

Sample user-facing error message

Account not currently supported

:

Your account is not currently supported. Please log in using a different account

Your user will be redirected to the Institution Select pane to connect a different account.

• Plaid does not currently support the types of accounts for the the connected Item, due to restrictions in place at the selected institution.
• Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution.
• The credentials provided are for a 'guest' account or other account type with limited account access.

Prompt the user to connect a different account and institution.

If the error persists and none of the common causes above seem to apply, contact Support.

Sample user-facing error message

Your account settings are incompatible

:

Your account could not be connected because the multi-factor authentication method it uses is not currently supported. Please try a different account.

Your user will be redirected to the Institution Select pane to connect a different account.

• Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution.
• The user's multi-factor authentication setting is configured not to remember trusted devices and instead to present a multi-factor challenge on every login attempt. This prevents Plaid from refreshing data asynchronously, which many products (especially Transactions) require.

Prompt the user to connect a different account and institution.

If your application does not require asynchronous data refresh to work properly, contact Support to explore your options for enabling user access.

If user's settings are not configured to present a multi-factor challenge on every login attempt but this error is still appearing, submit a 'Multi-factor authentication issues' Support ticket with the following identifiers: institution_id and either link_session_id or request_id.

Sample user-facing error message

No compatible accounts

:

Your credentials are correct, but we couldn’t find any accounts with this institution that are compatible with this application. Try another account, financial institution, or check for another connection method.

Your user will be redirected to the Institution Select pane to connect a different account.

• The user successfully logged into their account, but Plaid was unable to retrieve any open, active, or eligible accounts in the connected Item.
• The user closed their account.
• The user revoked access to the account.
• The account experienced account churn, which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked.
• There is a problem with Plaid's connection to the user's financial institution.

If you are using the account_filters parameter when calling /link/token/create, ensure that you are not filtering out valid accounts that could be used with your app.

If the Item is at institution that uses OAuth, ensure that the user has not denied or revoked OAuth access to all of their eligible accounts.

Ensure the user has not closed their account. If the user no longer has any open accounts associated with the Item, remove the Item via /item/remove.

Prompt the user to connect a different account and institution.

If this error persists and the user does have accounts at the institution that you should be able to access, please submit a Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

Sample user-facing error message

No eligible accounts

:

We didn't find any checking or savings accounts at this institution. Please try linking another institution

• /auth/get was called on an Item with no accounts that can support Auth, or accounts that do support Auth were filtered out. Only debitable checking and savings accounts can be used with Auth.
• Plaid's ability to retrieve Auth data from the institution has been temporarily disrupted.
• The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any debitable checking and savings accounts. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share account and routing number information even if they have already opted in to sharing information about their checking or savings account.
• The end user revoked access to the account.
• The account experienced account churn, which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked.

Ensure that any account_id specified in the options filter for /auth/get belongs to a debitable checking or savings account.

Ensure that the end user has a debitable checking or savings account at the institution. Not all savings and checking accounts permit ACH debits. Common examples of non-debitable accounts include savings accounts at Chime or at Navy Federal Credit Union (NFCU).

If the Item is at an OAuth-based institution, prompt the end user to allow Plaid to access a debitable checking or savings account, along with its account and routing number data. The end user should do this during the Link flow if they were unable to successfully complete the Link flow for the Item, or at their institution's online banking portal if the Item has already been added.

If you previously had access to the account, send your user through the update mode flow to allow them to re-grant access to the account.

Return your user to the Link flow and prompt them to link a different account.

If the problem persists even though the end user has confirmed that they have a debitable checking or savings account at the institution, open a support ticket.

Sample user-facing error message

No investment accounts

:

None of your accounts are investment accounts. Please connect using a different bank

• Link was initialized with the Investments product, but the user attempted to link an account with no investment accounts.
• The /investments/holdings/get or /investments/transactions/get endpoint was called, but there are no investment accounts associated with the Item.
• The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts.

Have the user open an investment account at the institution and then re-link, or link an Item that already has an investment account.

If your end user is connecting to an institution that uses OAuth-based flows (one for which the oauth field in the institution record is true), ensure that your end user consented to share details for an investment account.

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, open a support ticket.

• The /investments/holdings/get or /investments/transactions/get endpoint was called, but there are no investment accounts associated with the Item.
• The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts.

Have the user open an investment account at the institution and then re-link, or link an Item that already has an investment account. If the user links a new Item, delete the old one via /item/remove.

If your end user is connecting to an institution that uses OAuth-based flows (one for which the oauth field in the institution record is true), ensure that your end user consented to share details for an investment account.

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, open a support ticket.

Sample user-facing error message

No liability accounts

:

None of your accounts are liability accounts. Please connect using a different bank

• The /liabilities/get endpoint was called, but there are no supported liability accounts associated with the Item.
• The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any liabilities accounts.

Make sure the user has linked an Item with a supported account type and subtype. The account types supported for the Liabilities product are credit accounts with the subtype of credit card or paypal, and loan accounts with the subtype of student loan or mortgage.

If your end user is connecting to an institution that uses OAuth-based flows (one for which the oauth field in the institution record is true), ensure that your end user consented to share details for a credit card, student loan, PayPal credit account, or mortgage.

If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, open a support ticket.

• You requested a product that was not enabled for the current access token. Ensure it is included when when calling /link/token/create and create the Item again.

• /transactions/get was called before the first 30 days of transactions data could be extracted. This typically happens if the endpoint was called within a few seconds of linking the Item. It will also happen if /transactions/get was called for the first time on an Item that was not initialized with transactions in the /link/token/create call. Note that this error does not occur when using /transactions/sync; if called too early, /transactions/sync will simply fail to return any transactions.
• Occasionally, this error can occur upon calling /transactions/get if Plaid's attempt to extract transactions for the Item has failed, due to a connectivity error with the financial institution, and Plaid has never successfully extracted transactions for the Item in the past. If this happens, Plaid will continue to retry the extraction at least once a day.
• /signal/evaluate was called for the first time on a new Item before any balance data could be extracted for the Item. When called, /signal/evaluate will return a PRODUCT_NOT_READY error if cached balance data does not exist and new balance data could not be obtained after 15 seconds. For some customers who participated in the early phases of the Signal beta, /signal/evaluate will return PRODUCT_NOT_READY immediately if cached balance data is not available when /signal/evaluate is called.
• /auth/get was called on an Item that hasn't been verified, which is possible when using micro-deposit based verification.
• /investments/transactions/get was called before the investments data could be extracted. This typically happens when the endpoint is called with the option for async_update set to true, and called again within a few seconds of linking the Item. It will also happen if /investments/transactions/get (with async_update set to true) was called for the first time on an Item that was not initialized with investments in the /link/token/create call.

If you know at the point of Link initialization that you will want to use Transactions with the linked Item, initialize Link with transactions in order to start the product initialization process ahead of time. For more details, see Choosing how to initialize products.

Listen for the INITIAL_UPDATE webhook fired when the Transactions product is ready and only call /transactions/get after that webhook has been fired.

(If using Auth) Verify the Item manually, or wait for automated verification to succeed.

(For failures to /signal/evaluate) Wait a few seconds, then retry.

Listen for the HISTORICAL_UPDATE webhook fired when the Investments product is ready and only call /investments/transactions/get after that webhook has been fired.

• A product endpoint request was made for an Item that does not support that product. This can happen when trying to call a product endpoint on an Item if the product was not included in either the products or optional_products arrays when calling /link/token/create.
• A product endpoint request was made for an Item at an OAuth-based institution, but the end user did not authorize the Item for the specific product, or has revoked Plaid's access to the product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account. (This usage is deprecated; see also ACCESS_NOT_GRANTED.)
• Updated accounts have been requested for an Item initialized with the Assets product, which does not support adding or updating accounts after the initial Link.
• You are attempting to call /signal/evaluate on a non-US financial institution.
• You are attempting to call /transactions/refresh on a Capital One Item that contains only credit cards or other non-depository products. Capital One does not support the /transactions/refresh endpoint for non-depository products.
• You are attempting to call /identity/match on a Same-Day Micro-deposit-based Item that has not been seen on the Plaid network before.

Use the /item/get endpoint to determine which products a given Item supports.

Use the /institutions/get_by_id endpoint to determine which products a given institution supports. Receiving this error is expected if the user's institution does not support the requested product.

If the product is critical to your use case, put it in either the products or optional_products array when calling /link/token/create. Warning: making this change may reduce conversion, as it will block customers from linking their accounts if their institution doesn't support the product. For more details, see Choosing how to initialize products.

If the Item is at an OAuth-based institution, prompt the end user to allow Plaid to access the specific types of data your app needs. The end user should do this during the Link flow if they were unable to successfully complete the Link flow for the Item, or If the Item is at an OAuth-based institution, prompt the end user to allow Plaid to access identity data and/or account and routing number data. The end user should do this during the Link flow if they were unable to successfully complete the Link flow for the Item, or via Link's update mode if the Item has already been added.

If receiving this error during /link/token/create for update mode, and you are using the Item with the Assets product, you must instead create a new Item rather than updating the existing Item.

Sample user-facing error message

Action required with your account

:

Log in to your bank and update your account. Then, return to Plaid to continue.

Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account.

• The institution requires special configuration steps before the user can link their account with Plaid. KeyBank and Betterment are two examples of institutions that require this setup.
• The user’s account is not fully set up at their institution.
• The institution is blocking access due to an administrative task that requires completion. This error can arise for a number of reasons, the most common being:
  • The user must agree to updated terms and conditions.
  • The user must reset their password.
  • The user must enter additional account information.

Request that the user log in and complete their account setup directly at their institution.

Ask that the user log in to the bank, and confirm whether they are presented with some form of agreement page, modal, or some other actionable task. The user should also check their bank website for special settings to allow access for third-party apps, such as a "third party application password" or "allow third party access" setting.

This can usually be done completely online, but there are some financial institutions that require the user to call a phone number, or access a physical branch.

Once completed, prompt the user to re-authenticate with Plaid Link.

If the user is still unable to log in to their institution, please submit a 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

Sample user-facing error message

Session expired

:

Please re-enter your information to link your accounts.

• Your user did not complete the account selection flow within five minutes.

Have your user attempt to link their account again.