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.
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 correctlyAlternative 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
If the account number was correct and the account was a supported type, 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 invalid.
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 request parameter that is optional in the API schema was not provided in a context where it is required. For example,
/accounts/balance/get
was called without specifyingoptions.min_last_updated_datetime
on a Capital One (ins_128026
) Item with non-depository accounts. - The value used in the field is not valid for business logic reasons. For example,
/signal/decision/report
or/signal/return/report
endpoints were called with aclient_transaction_id
for which/signal/evaluate
was never called, or/transfer/create
was called using anauthorization_id
whosedecision
value isdeclined
. - A request to
/link/token/create
was sent specifying an OAuth redirect URI that was not added to the allowed redirect URIs list in the Dashboard.
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}