Troubleshoot query error codes

This is for:

Developer

This article explains why you may be getting certain error codes when performing a query with the Search API, and provides some common ways to handle these 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 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 or type error in one or more arguments of your query.

Examples

  • 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 queryFunction parameter may contain invalid JSON: [{"function":"@numberoflikes+1","fieldName":"adjustednumberoflikes",}].

Resolution

Ensure that all provided arguments match the type or 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.

Example

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

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 occurring because you’re authenticating using an Oauth2 token and you haven’t 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 query pipeline that’s specified in either the search token or the pipeline query parameter doesn’t exist in the target Coveo organization.

Resolution

Specify a valid pipeline parameter. If you’re authenticating using a search token which enforces a query pipeline, make sure that pipeline exists in the target 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:

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 fit into any of the preceding categories (for example, UnexpectedSoapErrorException).

Cause

It’s possible that some of your parameters are improperly formatted or empty, which can lead to unexpected errors (for example, queryFunctions or rankingFunctions may be set to [{}]).

Resolution

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

400 NO_REGISTERED_ENDPOINT

Symptom

The Search API returns a 400 error concerning the absence of a registered endpoint.

Cause

The organization has no registered endpoint, which can occur when the organization is either paused or isn’t properly configured.

Resolution

Check the status of your organization, and make sure it’s properly configured.

400 QUERY_PIPELINE_INTERRUPTED

Symptom

The Search API returns a 400 error concerning an interrupted query pipeline.

Cause

Regular expressions in query pipeline conditions may be overly complex or could benefit from refinement.

Resolution

Review your regular expressions in your pipeline conditions and make sure they aren’t too complex.

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 the Coveo Platform 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 that it has the right privileges, or create a new one which does.

  • Ensure that there aren’t any typos 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 (for example, 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 that you’re trying to reach doesn’t exist. Most of the time, this is due to a typo.

Resolution

Ensure that you’re using a valid endpoint. See the Search API Swagger documentation 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.

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.

500 FACET_SEARCH_FAILURE

Symptom

The Search API returns a 500 error concerning a failure in the facet search.

Cause

Internal issues when querying the index, resulting in search values not being retrieved.

Resolution

Contact Coveo Support.

503 ORGANIZATION_PAUSED

Symptom

The Search API returns a 503 error concerning the organization status.

Cause

The organization was paused due to inactivity.

Resolution

The organization should typically resume on its own in the next minutes. If the issue persists, contact Coveo Support.

503 SERVER_UNAVAILABLE

Symptom

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

Cause

  • Due to a temporary issue with Coveo indexes, no available index could process the request.

  • The index is experiencing a high volume of requests and can’t process the current request. When this happens, a Retry-After header will be set on the response, indicating the number of seconds to wait before retrying.

  • The current query is too complex to process within the allowed time.

Resolution

  • If there’s a temporary issue with Coveo indexes, it may resolve automatically; however, if the issue persists, it may require intervention from the Coveo team to restore normal operations.

  • If a Retry-After header appeared, wait for the time specified, then try the request again. If the issue persists or frequent throttling occurs, contact Coveo Support to optimize performance for the current workload.

  • Review your query to reduce its complexity so that it’s optimized for performance.

5XX

Symptom

The Search API returns an error with code 5XX.

Cause

You’ve 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. Typos or omissions that go unhandled can lead to 500 errors down the road.

    Examples

    • 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 availability of Coveo Platform services from the Coveo Service Status page.