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 aclient_id
andsecret
.
Troubleshooting steps
1http code 4002{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.
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
If the account number was correct, please contact Plaid Support.
1http code 4002{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 typeapplication/json
. The Plaid API only accepts JSON text as the MIME media type, withUTF-8
encoding, conforming to RFC 4627.
1content-type: 'application/json'
Troubleshooting steps
1http code 4002{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.
Troubleshooting steps
1http code 4002{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 specifyingoptions.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 aclient_transaction_id
for which/signal/evaluate
was never called.
Troubleshooting steps
1http code 4002{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 theContent-Type
header.
Troubleshooting steps
1http code 4002{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
1http code 4002{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
1http code 4002{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.
1http code 4002{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
1http code 4002{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
1http code 4002{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}