Errors

Issues and Warnings

There are three kinds of issues that can be reported for a given request:

FATAL_ERROR
- An issue caused the entire request to be rejected.
NON_FATAL_ERROR
- An item is rejected, but other items present in the request are accepted (e.g., one invalid Product List item).
- A field is rejected, but the item otherwise is accepted (e.g., invalid website URL in a Location).
WARNING
- The request did not adhere to our best practices or recommendations, but the data was accepted anyway (e.g., data was sent that may cause some listings to become unavailable, a deprecated API was used, or we changed the format of a field’s content to meet our requirements).

Status Codes

200 OK
- Either there are no errors or warnings, or the only issues are of type WARNING.
207 Multi-Status
- There are errors of type itemError or fieldError (but none of type requestError).
400 Bad Request
- A parameter is invalid, or a required parameter is missing. This includes the case where no API key is provided and the case where a resource ID is specified incorrectly in a path.
- This status is if any of the response errors are of type requestError.
401 Unauthorized
- The API key provided is invalid.
403 Forbidden
- The requested information cannot be viewed by the acting user.
404 Not Found
- The endpoint does not exist.
405 Method Not Allowed
- The request is using a method that is not allowed (e.g., POST with a GET-only endpoint).
409 Conflict
- The request could not be completed in its current state.
- Use the information included in the response to modify the request and retry.
429 Too Many Requests
- You have exceeded your rate limit / quota.
500 Internal Server Error
- Yext’s servers are not operating as expected. The request is likely valid but should be resent later.
504 Timeout
- Yext’s servers took too long to handle this request, and it timed out.

Errors and Debugging — Secure Token API

Opposed to other Yext APIs, the Secure Token API does not return non-fatal errors or warnings. Because of this, error responses will never contain a valid token.

400 Errors

Invalid JSON Parameters Error

Example Error Response:

 {
     "body": {},
     "statusCode": 400,
     "error": [
         {
             "code": 46,
             "type": 1,
             "message": "Invalid/improperly formatted parameters specified in the request body"
         }
     ]
 }

This error occurs when there is an issue with the JSON in the request body. A list of potential causes include:

The body of the request contains invalid JSON.
The body of the request is missing one or more required parameters.
The body of the request contains one or more unknown parameters.
The body of the request contains one or more valid parameters whose value is not the correct type.

If this error occurs, inspect the body of the request, ensuring the JSON is valid both in structure and contents. The request body should only contain the required parameters and the value for each parameter is of the correct type.

Invalid expires_in Value Error

Example Error Response:

 {
     "body": {},
     "statusCode": 400,
     "error": [
         {
             "code": 46,
             "type": 1,
             "message": "the expires_in parameter must be an integer between 60 and 1440. The expires_in parameter determines the number of minutes a token will be valid for"
         }
     ]
 }

This error occurs when the value of the expires_in parameter is an integer that is not within the range of [60, 1440]. If this error occurs, check the expires_in parameter located within the request body and modify the parameter to be a valid value.

“None” Algorithm Specified Error

Example Error Response:

 {
     "body": {},
     "statusCode": 400,
     "error": [
         {
             "code": 46,
             "type": 1,
             "message": "the signing method specified cannot be 'none'"
         }
     ]
 }

This error occurs when the value of the signing_algorithm parameter has been set to “none”. To ensure that the Api Tokens returned by the Secure Token Creation endpoint are secure, a valid signing algorithm must be specified. Valid values include:

HS256
RS256
ES256

If this error occurs, check the signing_algorithm parameter located within the request body and ensure it is valid.

Unknown Algorithm Specified Error

Example Error Response:

 {
     "body": {},
     "statusCode": 400,
     "error": [
         {
             "code": 46,
             "type": 1,
             "message": "the signing method specified is missing or not valid"
         }
     ]
 }

401 Errors

Invalid Api Key Error

Example Error Response:

 {
     "body": {},
     "statusCode": 401,
     "error": [
         {
             "code": 1,
             "type": 1,
             "message": "invalid api key"
         }
     ]
 }

This error occurs when the provided API key is not a valid Yext API Key. If this error occurs, check the value of the api_key parameter in the request body.

Missing API Key

Example Error Response:

{
     "body": {},
     "statusCode": 401,
     "error": [
         {
             "code": 1,
             "type": 1,
             "message": "missing api key"
         }
     ]
 }

This error occurs when an API key is not provided in the request body. The API key cannot be provided in the query string or request header.

Insufficient Permissions Error

Example Error Response:

 {
     "body": {},
     "statusCode": 401,
     "error": [
         {
             "code": 1,
             "type": 1,
             "message": "the provided api key does not have permissions to create a token"
         }
     ]
 }

This error occurs when the provided API key is a valid Yext API key but does not have the permission that enables the API key to be used to create Secure API Tokens. If this error occurs, log into your Yext account and check the app details in your Developer Console. If your app has the appropriate permissions but you are still encountering this error, please contact Yext support.

405 Errors

Method Not Allowed Error

Example Error Response:

{
     "body": {},
     "statusCode": 405,
     "error": [
         {
             "code": 46,
             "type": 1,
             "message": "HTTP method _____ not allowed for this resource."
         }
     ]
 }

This error occurs when the HTTP method of a request is not POST. If this error occurs, check to make sure you are sending a POST request.

415 Errors

Missing Content-Type Error

Example Error Response:

{
     "body": {},
     "statusCode": 415,
     "error": [
         {
             "code": 6,
             "type": 1,
             "message": "Missing Content-Type. You must provide a content type of application/json"
         }
     ]
 }

This error occurs when the Content-Type header of the request was not set. If this error occurs, set the Content-Type header to application/json and retry the request. Note that setting the request body to valid JSON does not necessarily mean the Content-Type header will be set to application/json.

Invalid Content-Type Error

Example Error Response:

{
     "body": {},
     "statusCode": 415,
     "error": [
         {
             "code": 6,
             "type": 1,
             "message": "Invalid Content-Type ____. You must provide a content type of application/json"
         }
     ]
 }

This error occurs when the Content-Type header of the request was set to a value other than application/json. If this error occurs, set the Content-Type header to application/json and retry the request.

429 Errors

Too Many Requests Error

Example Error Response:

{
     "body": {},
     "statusCode": 429,
     "error": [
         {
             "code": 42,
             "type": 1,
             "message": "You have exceeded your hourly token creation limit"
         }
     ]
 }

This error occurs when the number of requests to the CreateToken endpoint exceeds 100,000 requests within an hour. Limits are reset at the start of each hour. If you believe you are being incorrectly rate-limited, please contact Yext support.

500 Errors

Internal Server Error

Example Error Response:

 {
     "body": {},
     "statusCode": 500,
     "error": [
         {
             "code": 9,
             "type": 1,
             "message": "We had a problem with our software. Please contact support!"
         }
     ]
 }

This error occurs when an issue with Yext software is interfering with the normal serving of requests or if Yext is currently experiencing a temporary service outage and service will resume shortly. If this error occurs, please contact Yext support.

Feedback