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.

Server-Side

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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INCOMPATIBLE_API_VERSION",
 "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.",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

INVALID_ACCOUNT_NUMBER

The provided account number was invalid.

Server-SideorClient-Side

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.

Troubleshooting steps

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

If the account number was correct, please contact Plaid Support.

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

INVALID_BODY

The request body was invalid.

Server-Side

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
1
content-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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_BODY",
 "error_message": "body could not be parsed as JSON",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

INVALID_CONFIGURATION

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

Server-Side

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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_CONFIGURATION",
 "error_message": "please ensure that the request body is formatted correctly",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

INVALID_FIELD

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

Server-Side

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, is being provided for a field where PII is not allowed, such as user.client_user_id.
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.

Troubleshooting steps

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

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

INVALID_HEADERS

The request was missing a required header.

Server-Side

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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_HEADERS",
 "error_message": "{{ error message is specific to the given / missing header }}",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

MISSING_FIELDS

The request was missing one or more required fields.

Server-Side

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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "MISSING_FIELDS",
 "error_message": "the following required fields are missing: {fields}",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

NO_LONGER_AVAILABLE

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

Server-Side

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

NOT_FOUND

The endpoint requested does not exist.

Server-Side

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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "NOT_FOUND",
 "error_message": "not found",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

SANDBOX_ONLY

The requested endpoint is only available in Sandbox.

Server-Side

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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "SANDBOX_ONLY",
 "error_message": "access to {api/route} is only available in the sandbox environment at https://sandbox.plaid.com/",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}

UNKNOWN_FIELDS

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

Server-Side

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
1
2
3
4
5
6
7
8
http code 400 
{
 "error_type": "INVALID_REQUEST",
 "error_code": "UNKNOWN_FIELDS",
 "error_message": "the following fields are not recognized by this endpoint: {fields}",
 "display_message": null,
 "request_id": "HNTDNrA8F1shFEW"
}