Troubleshoot query error codes

Troubleshoot query error codes

This article explains why you may be getting certain error codes when performing a query with the Search API, and provides some of the most common ways to handle those errors.

400 BAD_REQUEST

Invalid JSON

Symptom

The Search API returns an error concerning invalid JSON.

Cause

You’re using the POST method to perform a query with the Search API and your request body is incorrectly formatted.

Resolution

Use a JSON validation tool to ensure that the body of your call is valid JSON. If the request body of your query is fairly short, you may want to consider using the GET method rather than POST. Doing so implies that you must pass all arguments as query string parameters rather than as JSON key-value pairs in the request body.

Invalid element

Symptom

The Search API returns an error concerning an invalid field, parameter, value, or expression in your query.

Cause

There may be a typo or a format/type error in one or more arguments of your query.

Resolution

Ensure all provided arguments match the type/format required by the Search API.

Missing element

Symptom

The Search API returns an error concerning a missing element in your query.

Cause

This error is typically the result of a missing value in a JSON key-value pair.

Resolution

Ensure that you correctly provide whichever elements are required in your query to the Search API. While all top-level query parameters are optional, objects in complex array-type parameters such as groupBy do have required properties when specified.

Unspecified organization

Symptom

The Search API returns an error concerning your organization being unspecified.

Cause

This error is most likely due to the fact that you’re authenticating using an Oauth2 token and you have not provided a value for the organizationId parameter.

Resolution

Provide a valid organizationId parameter, or authenticate your query with an API key or a search token, which are intrinsically linked to a specific organization.

Unrecognized query pipeline

Symptom

The Search API returns an error concerning the query pipeline you’re trying to use.

Cause

The specified pipeline (either in the search token or the pipeline query parameter) doesn’t exist in the target Coveo organization, if not already done.

Resolution

Specify a valid pipeline parameter, or, if your are authenticating using a search token which enforces a pipeline, make sure that pipeline exists in the target Coveo organization, if not already done.

Response size too large

Symptom

The Search API returns an error stating that the size of the response is too large. Typically, this happens when exporting index content with the Export to Excel component or the Coveo CLI.

Cause

The size of the response is affected by the:

• Number of search results (numberOfResults parameter)

• Number of fields (fieldsToInclude parameter)

• Amount of data in the fields

• Amount of debug information (debug parameter)

Resolution

To reduce the size of the response, you can:

• Export fewer search results

• Export results with a lower number of fields

• Exclude from exports results with a significant amount of metadata

• Disable debug mode

Other

Symptom

You may get an unexpected 400 error which doesn’t neatly fit any of the above categories (e.g., UnexpectedSoapErrorException).

Cause

It’s possible that some of your parameters are improperly formatted or empty, which leads to unexpected errors down the road (e.g., queryFunctions or rankingFunctions may be set to [{}]).

Resolution

Ensure that you correctly provide whichever elements are required in your query to the Search API.

401 UNAUTHORIZED

Invalid token

Symptom

The Search API returns an error concerning your access token being invalid.

Cause

• If you’re authenticating with an Oauth2 token, it may be expired.

• If you’re authenticating with an API key, it may have been disabled or deleted in the target, or your IP address may not have access to this key.

• There may be a typo in the access token you’re trying to use, resulting in Coveo not recognizing it.

Resolution

• If you’re authenticating with an Oauth2 token, try again using a fresh one.

• If you’re authenticating with an API key, ensure it has the right privileges, or create a new one which does.

• Ensure that there’s no typo in your access token.

Missing authentication

Symptom

The Search API returns an error concerning missing authentication.

Cause

The Authorization header may be absent or improperly formatted (e.g., you may have input Baerer instead of Bearer).

Resolution

Ensure that you provide a header of the form Authorization: Bearer <token>, where <token> is your access token.

403 FORBIDDEN

Access denied

Symptom

The Search API returns an error concerning your access being denied.

Cause

Typically, this error occurs when you’re authenticating using an API key which doesn’t have the privilege to execute queries.

Resolution

Modify the API key accordingly, or create a new API key with the required privilege.

404 NOT_FOUND

Symptom

The Search API returns an error concerning its inability to locate the specified endpoint.

Cause

The Search API endpoint you’re trying to reach doesn’t exits. Most of the time, this is due to a typo.

Resolution

Ensure that you’re using a valid endpoint (see https://platform.cloud.coveo.com/docs?api=SearchApi for the list of available Search API endpoints).

419

Expired token

Symptom

The Search API returns an error message concerning your access token being expired.

Cause

Typically, this error occurs when you’re authenticating using an expired search token.

Resolution

Try again using a fresh search token (see Request a Search Token).

429 TOO_MANY_REQUESTS

Symptom

The Search API returns an error concerning too many requests being made to the Search API.

Cause

The Search API is using throttling to protect the API, meaning that some requests are refused or slowed down.

Resolution

Wait until your calls are no longer being throttled before using the service again. In the future, ensure that you make Push API calls at a slower pace.

503 SERVER_UNAVAILABLE

Symptom

The Search API returns an error concerning the service being unavailable.

Cause

• Your organization may be paused.

• Your index may be overloaded.

Resolution

• If your organization is paused, log in to the Coveo Administration Console to reactivate it.

• If your index is overloaded, try performing the operation again with exponentially longer backoff times.

5XX

Symptom

The Search API returns an error with code 5XX.

Cause

You have triggered an unhandled error, or there’s an issue with the Search API service itself.

Resolution

• Ensure that your query is properly formatted and contains all required values. Simple typos or omissions that go unhandled can lead to 500 errors down the road.

  • Setting "q{}":"coveo" throws a 500 error.

  • Setting groupBy to [{"field":"@author","computedFields":[{"field":"field"}]}], where the operation value is missing, throws a 500 error.

• If you’re obviously not responsible for the error, try performing the operation again (with an exponential backoff).

• You can monitor the status of Coveo from status.cloud.coveo.com.