Item Errors

Guide to troubleshooting Item errors

INSTANT_MATCH_FAILED

Instant Match could not be initialized for the Item.
Server-Side
Common causes
  • 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.
Troubleshooting steps
1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INSTANT_MATCH_FAILED",
"error_message": "Item cannot be verified through Instant Match. Ensure you are correctly enabling all auth features in Link.",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

INSUFFICIENT_CREDENTIALS

The user did not provide sufficient authorization in order to link their account via an OAuth login flow.
Server-SideorClient-Side
Common causes
  • Your user abandoned the bank OAuth flow without completing it.
Troubleshooting steps

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INSUFFICIENT_CREDENTIALS",
"error_message": "insufficient authorization was provided to complete the request",
"display_message": "INSUFFICIENT_CREDENTIALS",
"request_id": "HNTDNrA8F1shFEW"
}

INVALID_CREDENTIALS

The financial institution indicated that the credentials provided were invalid.
Client-Side
Link user experience

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

Common causes
  • 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 and Betterment are two 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.
    • For example: a user may have selected Fidelity instead of Fidelity - NetBenefits. This confusion is particularly common between Fidelity (brokerage accounts) and Fidelity NetBenefits (retirement accounts) and 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.
Troubleshooting steps

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

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INVALID_CREDENTIALS",
"error_message": "the provided credentials were not correct",
"display_message": "The provided credentials were not correct. Please try again.",
"request_id": "HNTDNrA8F1shFEW"
}

INVALID_MFA: OTP Device & Code

The institution indicated that the provided response for the selected device and OTP code was invalid.
Client-Side
Link user experience

Your user will be redirected to the MFA Device pane to reselect their multi-factor authentication device and re-enter their one-time code.

Common causes
  • 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.
Troubleshooting steps

If the user does not receive a one-time code or still cannot succeed with a current MFA device login, please submit a 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INVALID_MFA",
"error_message": "the provided MFA response(s) were not correct",
"display_message": "The provided MFA responses were not correct. Please try again.",
"request_id": "HNTDNrA8F1shFEW"
}

INVALID_MFA: Questions

The institution indicated that the provided response for MFA Questions was invalid.
Client-Side
Link user experience

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

Common causes
  • The user entered an incorrect answer for the security question presented by the selected institution.
Troubleshooting steps

If the user still cannot log in despite providing correct answers to their security questions, please submit a 'Invalid credentials errors' Support ticket with the following identifiers: access_token, institution_id, and either link_session_id or request_id.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INVALID_MFA",
"error_message": "the provided MFA response(s) were not correct",
"display_message": "The provided MFA responses were not correct. Please try again.",
"request_id": "HNTDNrA8F1shFEW"
}

INVALID_MFA: Selections

The institution indicated that the provided response for MFA Selections was invalid.
Client-Side
Link user experience

Your user will be redirected to the MFA Selections pane to retry selecting the correct answers.

Common causes
  • The user provided an incorrect answer to the security question.
Troubleshooting steps
1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INVALID_MFA",
"error_message": "the provided MFA response(s) were not correct",
"display_message": "The provided MFA responses were not correct. Please try again.",
"request_id": "HNTDNrA8F1shFEW"
}

INVALID_SEND_METHOD

Returned when the method used to send MFA credentials was deemed invalid by the insitution.
Client-Side
Link user experience

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

Common causes
  • The institution is experiencing login issues.
  • The integration between Plaid and the financial institution is experiencing errors.
Troubleshooting steps

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INVALID_SEND_METHOD",
"error_message": "the provided MFA send_method was invalid",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

INVALID_UPDATED_USERNAME

The username entered during update mode did not match the original username.
Client-Side
Link user experience

Your user will be directed to enter a different username.

Common causes
  • 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.
Troubleshooting steps
1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "INVALID_UPDATED_USERNAME",
"error_message": "the username provided to /item/credentials/update does not match the original username for the item",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

ITEM_LOCKED

The financial institution indicated that the user's account is locked. The user will need to work with the institution directly to unlock their account.
Client-Side
Link user experience

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.

Common causes
  • 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.
Troubleshooting steps

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "ITEM_LOCKED",
"error_message": "the account is locked. prompt the user to visit the institution's site and unlock their account",
"display_message": "The given account has been locked by the financial institution. Please visit your financial institution's website to unlock your account.",
"request_id": "HNTDNrA8F1shFEW"
}

ITEM_LOGIN_REQUIRED

The financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.
Server-Side
Developer experience

This error is frequently encountered during a /[product]/get request.

Common causes
  • The user changed their password.
  • The user changed their multi-factor authentication device, questions, or answers.
  • The institution updated its multi-factor security protocols.
  • The Item is associated with Chase Bank, which is requiring a mandatory one-time re-sync for all end-users who have connected their Chase accounts through any 3rd party aggregator. This event is being staggered throughout March 2021 and will only occur once for all such end-users.
Troubleshooting steps

If the error is legitimate, having the user authenticate again should 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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "ITEM_LOGIN_REQUIRED",
"error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

ITEM_NO_ERROR or item-no-error

The Link flow in update mode was entered for an Item that is already in a good state. No further action is required.
Client-Side
Link user experience

Your user will see the Success pane, prompting them to continue and finish reconnecting their account.

Common causes
  • Link was initialized in Update mode for an Item that is already in a good state and does not need to be updated.

No further action is required – the ITEM_LOGIN_REQUIRED error for the given Item has been resolved, and you can fetch product data again.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "ITEM_NO_ERROR",
"error_message": "The item provided cannot be updated. Only items in an error state or OAuth items may have their credentials updated.",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

ITEM_NOT_FOUND

The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user
Server-Side
Common causes
Troubleshooting steps
1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "ITEM_NOT_FOUND",
"error_message": "The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user.",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

ITEM_NOT_SUPPORTED

Plaid is unable to support this user's accounts due to restrictions in place at the financial institution.
Client-Side
Link user experience

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

Common causes
  • 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.
Troubleshooting steps

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

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "ITEM_NOT_SUPPORTED",
"error_message": "this account is currently not supported",
"display_message": "The given account is not currently supported for this financial institution. We apologize for the inconvenience.",
"request_id": "HNTDNrA8F1shFEW"
}

MFA_NOT_SUPPORTED

Returned when the user requires a form of MFA that Plaid does not support for a given financial institution.
Client-Side
Link user experience

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

Common causes
  • 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.
Troubleshooting steps

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "MFA_NOT_SUPPORTED",
"error_message": "this account requires a MFA type that we do not currently support for the institution",
"display_message": "The multi-factor security features enabled on this account are not currently supported for this financial institution. We apologize for the inconvenience.",
"request_id": "HNTDNrA8F1shFEW"
}

NO_ACCOUNTS

Returned when there are no open accounts associated with the Item.
Client-Side
Link user experience

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

Common causes
  • The user successfully logged into their account, but Plaid was unable to retrieve any open or active accounts in the connected Item.
Troubleshooting steps

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "NO_ACCOUNTS",
"error_message": "no valid accounts were found for this item",
"display_message": "No valid accounts were found at the financial institution. Please visit your financial institution's website to confirm accounts are available.",
"request_id": "HNTDNrA8F1shFEW"
}

NO_AUTH_ACCOUNTS or no-depository-accounts

Returned from POST /auth/get when there are no valid checking or savings account(s) for which account and routing numbers could be retrieved.
Server-SideorClient-Side
Common causes
  • /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.
Troubleshooting steps

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "NO_AUTH_ACCOUNTS",
"error_message": "There are no valid checking or savings account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more.",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

NO_INVESTMENT_ACCOUNTS

Returned from POST /investments/holdings/get, POST /investments/transactions/get, or Link initialized with the Investments product, when there are no valid investment account(s) for which holdings or transactions could be retrieved.
Server-SideorClient-Side
Common causes
  • 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.
Troubleshooting steps

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

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "NO_INVESTMENT_ACCOUNTS",
"error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

NO_INVESTMENT_AUTH_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.
Server-Side
Common causes
  • 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.
Troubleshooting steps

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

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "NO_INVESTMENT_AUTH_ACCOUNTS",
"error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

NO_LIABILITY_ACCOUNTS

Returned from POST /liabilities/get when there are no valid liability account(s) for which liabilities could be retrieved.
Server-Side
Common causes
  • 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.
Troubleshooting steps

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

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "NO_LIABILITY_ACCOUNTS",
"error_message": "There are no valid liability account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

PRODUCT_NOT_READY

Returned when a data request has been made for a product that is not yet ready.
Server-Side
Common causes
Troubleshooting steps
1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "PRODUCT_NOT_READY",
"error_message": "the requested product is not yet ready. please provide a webhook or try the request again later",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

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.
Server-Side
Common causes
  • A product endpoint request was made for an Item that does not support that product.
  • 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.
Troubleshooting steps
1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "PRODUCTS_NOT_SUPPORTED",
"error_message": "",
"display_message": null,
"request_id": "HNTDNrA8F1shFEW"
}

USER_SETUP_REQUIRED

The user must log in directly to the financial institution and take some action before Plaid can access their accounts.
Client-Side
Link user experience

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.

Common causes
  • 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.
Troubleshooting steps

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.

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.

1
2
3
4
5
6
7
8
http code 400
{
"error_type": "ITEM_ERROR",
"error_code": "USER_SETUP_REQUIRED",
"error_message": "the account has not been fully set up. prompt the user to visit the issuing institution's site and finish the setup process",
"display_message": "The given account is not fully setup. Please visit your financial institution's website to setup your account.",
"request_id": "HNTDNrA8F1shFEW"
}