Troubleshooting 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 are 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.

  • The partialmatchKeywords parameter may be set to 3.0 instead of 3.
  • The sortCriteria parameter may be set to DateDescending,@size descending instead of Date Descending,@size descending.
  • The indexType parameter may be set to elasticSearch instead of elasticsearch.
  • The queryFunction parameter may contain invalid JSON: [{"function":"@numberoflikes+1","fieldName":"adjustednumberoflikes",}].

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.

The groupBy parameter may be set to [{"field":"@author","computedFields":[{}]}] instead of [{"field":"@author","computedFields":[{"field": "@wordcount","operation": "average"}]}].

Resolution

Ensure 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 are 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 are trying to use.

Cause

The specified pipeline (either in the search token or the pipeline query parameter) does not exist in the target Coveo Cloud organization.

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 Cloud organization.

Other

Symptom

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

Cause

It is 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 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 are authenticating with an Oauth2 token, it may be expired. If you are 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 are trying to use, resulting in the Coveo Cloud platform not recognizing it.

Resolution

  • If you are authenticating with an Oauth2 token, try again using a fresh one.
  • If you are authenticating with an API key, ensure it has the right privileges, or create a new one which does.
  • Ensure there is 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 are authenticating using an API key which does not 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 are trying to reach does not exits. Most of the time, this is due to a typo.

Resolution

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

408 REQUEST_TIMEOUT

Symptom

The Search API returns an error concerning the server being unavailable when connecting to the Search API.

Cause

A variety of issues can cause this error, such as the index being overloaded or unresponsive, and other unspecified errors in the Search API.

Resolution

Typically, this can be resolved by reviewing the status of your organization to ensure it is HEALTHY (see Review the Status of Your Organization and the Coveo Cloud Platform).

419

Expired Token

Symptom

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

Cause

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

Resolution

Try again using a fresh search token (see Requesting 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.

5XX

Symptom

The Search API returns an error with code 5XX.

Cause

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

Resolution

  • Ensure 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 are obviously not responsible for the error, try performing the operation again (with an exponential backoff).
  • You can monitor the status of the Coveo Cloud platform from status.cloud.coveo.com.

Coveo for Salesforce Free Error Messages

If you are using Coveo for Salesforce Free, the Search API may return errors which are specific to this particular integration (see Coveo for Salesforce Free Error Messages).