Invalid Request Errors

Guide to troubleshooting invalid request errors

INCOMPATIBLE_API_VERSION

The request uses fields that are not compatible with the API version being used.

Common causes

The API endpoint was called using a public_key for authentication rather than a client_id and secret.

Troubleshooting steps

Review the API Reference for the endpoint to see what parameters are supported in the API version you are using.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INCOMPATIBLE_API_VERSION",
5 "error_message": "The public_key cannot be used for this endpoint as of version {version-date} of the API. Please use the client_id and secret instead.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_ACCOUNT_NUMBER

The provided account number was invalid.

Sample user-facing error message

Account or routing number incorrect: Check with your bank and make sure that your account and routing numbers are entered correctly

Alternative user-facing error message

Account is not checking or savings: This account is not a valid checking or savings account and does not support ACH debit. Please retry with a different account.

Common causes

While in the Instant Match, Automated Micro-deposit, or Same-Day Micro-deposit Link flows, the user provided an account number whose last four digits did not match the account mask of their bank account.
If the user entered the correct account number, Plaid may have been unable to retrieve an account mask.
If the user entered the correct account number, the account type associated with the account may not be a supported Auth account type.

Troubleshooting steps

Have the user confirm that they entered the correct account number.

Have the user confirm that the account is a debitable checking or savings account. Other depository account types, such as money market accounts, are not supported by Auth.

If the account number was correct and the account was a supported type, please contact Plaid Support.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_ACCOUNT_NUMBER",
5 "error_message": "The provided account number was invalid.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_BODY

The request body was invalid.

Common causes

The JSON request body was malformed.
The request content-type was not of type application/json. The Plaid API only accepts JSON text as the MIME media type, with UTF-8 encoding, conforming to RFC 4627.

API request content-type
Copy
1content-type: 'application/json'

Troubleshooting steps

Resend the request with content-type: 'application/json'.

Resend the request with valid JSON in the body.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_BODY",
5 "error_message": "body could not be parsed as JSON",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_CONFIGURATION

/link/token/create was called with invalid configuration settings

Common causes

One or more of the configuration objects provided to /link/token/create does not match the request schema for that endpoint.

Verify that all field names being provided to /link/token/create match the schema for that endpoint. In particular, when migrating from Link tokens, note that some field names have changed between those used for Link token style Link configuration and those used as parameters for /link/token/create.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_CONFIGURATION",
5 "error_message": "please ensure that the request body is formatted correctly",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_FIELD

One or more of the request body fields were improperly formatted or an invalid type.

Common causes

One or more fields in the request body were invalid, malformed, or used a wrong type. The error_message field will specify the erroneous field and how to resolve the error.
Personally identifiable information (PII), such as an email address or phone number, was provided for a field where PII is not allowed, such as user.client_user_id.
An unsupported country code was used in Production. Consult the API Reference for the endpoint being used for a list of valid country codes.
An optional parameter was not provided in a context where it is required. For example, /accounts/balance/get was called without specifying options.min_last_updated_datetime on an Item whose institution requires that parameter to be specified.
The /signal/decision/report or /signal/return/report endpoints were called with a client_transaction_id for which /signal/evaluate was never called.

Troubleshooting steps

Resend the request with the correctly formatted fields specified in the error_message.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_FIELD",
5 "error_message": "{{ error message is specific to the given / missing request field }}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

INVALID_HEADERS

The request was missing a required header.

Common causes

The request was missing a header, typically the Content-Type header.

Troubleshooting steps

Resend the request with the missing headers.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "INVALID_HEADERS",
5 "error_message": "{{ error message is specific to the given / missing header }}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

MISSING_FIELDS

The request was missing one or more required fields.

Common causes

The request body is missing one or more required fields. The error_message field will list the missing field(s).

Troubleshooting steps

Resend the request with the missing required fields specified in the error_message.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "MISSING_FIELDS",
5 "error_message": "the following required fields are missing: {fields}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

NO_LONGER_AVAILABLE

The endpoint requested is not available in the API version being used.

Common causes

The endpoint you requested has been discontinued and no longer exists in the Plaid API.

Troubleshooting steps

Review the API Reference to see what endpoints are supported in the API version you are using.

See the Link Token migration guide for instructions on migrating away from endpoints that have been discontinued in recent API versions.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "NO_LONGER_AVAILABLE",
5 "error_message": "This endpoint has been discontinued as of version {version-date} of the API.",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

NOT_FOUND

The endpoint requested does not exist.

Common causes

The endpoint you requested does not exist in the Plaid API.

Troubleshooting steps

Navigate to the API reference to find the correct API endpoint.

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

Was this helpful?

SANDBOX_ONLY

The requested endpoint is only available in Sandbox.

Common causes

The requested endpoint is only available in the Sandbox API Environment.

Troubleshooting steps

Change your environment to Sandbox or remove usages of test endpoints.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "SANDBOX_ONLY",
5 "error_message": "access to {api/route} is only available in the sandbox environment at https://sandbox.plaid.com/",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}

Was this helpful?

UNKNOWN_FIELDS

The request included a field that is not recognized by the endpoint.

Common causes

The request body included one or more extraneous fields. The error_message field will list the unrecognized field(s).

Troubleshooting steps

Resend the request with the omitted fields specified in the error_message.

API error response
Copy
1http code 400
2{
3 "error_type": "INVALID_REQUEST",
4 "error_code": "UNKNOWN_FIELDS",
5 "error_message": "the following fields are not recognized by this endpoint: {fields}",
6 "display_message": null,
7 "request_id": "HNTDNrA8F1shFEW"
8}