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
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

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

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.
1
content-type: 'application/json'
Troubleshooting steps
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.
Troubleshooting steps
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
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
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
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
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
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
Troubleshooting steps
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
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"
}