---
title: Troubleshoot query error codes
slug: '1471'
canonical_url: https://docs.coveo.com/en/1471/
collection: build-a-search-ui
source_format: adoc
---
# Troubleshoot query error codes
This article explains why you may be getting certain error codes when performing a [query](https://docs.coveo.com/en/231/) with the Search API, and provides some examples and common ways to handle these errors.

> **Note**
>
> The examples in this article illustrate common error scenarios, but the JSON response body of the Search API error response may differ slightly in content depending on the situation.
> The `message` field is typically present and provides a human-readable explanation.
> However, the `errorCode` field is optional and may not appear in all error responses.

## 400 BAD_REQUEST

400 BAD_REQUEST is a generic error code that indicates that the request sent to the Search API was malformed or invalid.

### Invalid JSON

**Symptom**

The Search API returns an error concerning invalid JSON.

**Example**

```json
{
  "statusCode": 400,
  "message": "Invalid JSON format in request body."
}
```

**Cause**

You're using the POST method to perform a [query](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/200/), parameter, value, or expression in your [query](https://docs.coveo.com/en/231/).

**Example**

```json
{
  "statusCode": 400,
  "message": "Invalid value provided for one or more parameters."
}
```

**Cause**

There may be a typo or a format or type error in one or more arguments of your [query](https://docs.coveo.com/en/231/).

**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](https://docs.coveo.com/en/13/).

### Missing element

**Symptom**

The Search API returns an error concerning a missing element in your [query](https://docs.coveo.com/en/231/).

**Example**

```json
{
  "statusCode": 400,
  "message": "A required element is missing in the request."
}
```

**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](https://docs.coveo.com/en/231/) to the [Search API](https://docs.coveo.com/en/13/).
While all top-level [query](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/185/) being unspecified.

**Example**

```json
{
  "statusCode": 400,
  "message": "The parameter is missing: 'organizationId'"
}
```

**Cause**

This error is most likely occurring because you're [authenticating](https://docs.coveo.com/en/2120/) using an Oauth2 token and you haven't provided a value for the `organizationId` parameter.

**Resolution**

Provide a valid `organizationId` parameter, or [authenticate](https://docs.coveo.com/en/2120/) your [query](https://docs.coveo.com/en/231/) with an API key or a [search token](https://docs.coveo.com/en/1346/), which are intrinsically linked to a specific [organization](https://docs.coveo.com/en/185/).

### Unrecognized query pipeline

**Symptom**

The Search API returns an error concerning the [query pipeline](https://docs.coveo.com/en/180/) you're trying to use.

**Example**

```json
{
  "statusCode": 400,
  "message": "Unknown query pipeline: name or id \"some-unknown-name\""
}
```

**Cause**

The [query pipeline](https://docs.coveo.com/en/180/) that's specified in either the [search token](https://docs.coveo.com/en/1346/) or the `pipeline` [query](https://docs.coveo.com/en/231/) parameter doesn't exist in the target [Coveo organization](https://docs.coveo.com/en/185/).

**Resolution**

Specify a valid `pipeline` parameter.
If you're [authenticating](https://docs.coveo.com/en/2120/) using a [search token](https://docs.coveo.com/en/1346/) which enforces a [query pipeline](https://docs.coveo.com/en/180/), make sure that pipeline exists in the target [organization](https://docs.coveo.com/en/185/), 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](https://docs.coveo.com/en/204/) content with the [Export to Excel component](https://docs.coveo.com/en/3214/) or the [Coveo CLI](https://docs.coveo.com/en/cli/).

**Example**

```json
{
  "statusCode": 400,
  "message": "The response size exceeds the allowed limit."
}
```

**Cause**

The size of the response is affected by the:

* Number of search results ([`numberOfResults` parameter](https://docs.coveo.com/en/13#operation/searchUsingPost-numberOfResults))

* Number of [fields](https://docs.coveo.com/en/200/) ([`fieldsToInclude` parameter](https://docs.coveo.com/en/13#operation/searchUsingPost-fieldsToInclude))

* Amount of data in the [fields](https://docs.coveo.com/en/200/)

* Amount of debug information ([`debug` parameter](https://docs.coveo.com/en/13#operation/searchUsingPost-debug))

**Resolution**

To reduce the size of the response, you can:

* Export fewer search results

* Export results with a lower number of [fields](https://docs.coveo.com/en/200/)

* Exclude from exports results with a significant amount of [metadata](https://docs.coveo.com/en/218/)

* 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`).

**Example**

```json
{
  "statusCode": 400,
  "message": "An unexpected error occurred while processing the request."
}
```

**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](https://docs.coveo.com/en/231/) to the [Search API](https://docs.coveo.com/en/13/).

## 400 NO_REGISTERED_ENDPOINT

**Symptom**

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

**Example**

```json
{
  "statusCode": 400,
  "message": "No registered endpoint found for this organization.",
  "errorCode": "NO_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](https://docs.coveo.com/en/180/).

**Example**

```json
{
  "statusCode": 400,
  "message": "Failed to evaluate your query as some conditions in your pipeline took too much time.",
  "errorCode": "QUERY_PIPELINE_INTERRUPTED"
}
```

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

**Example**

```json
{
  "statusCode": 401,
  "message": "Invalid access token.",
  "errorCode": "UNAUTHORIZED"
}
```

**Cause**

* If you're [authenticating](https://docs.coveo.com/en/2120/) with an Oauth2 token, it may be expired.

* If you're [authenticating](https://docs.coveo.com/en/2120/) 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](https://docs.coveo.com/en/186/) not recognizing it.

**Resolution**

* If you're [authenticating](https://docs.coveo.com/en/2120/) with an Oauth2 token, try again using a fresh one.

* If you're [authenticating](https://docs.coveo.com/en/2120/) with an API key, ensure that it has the right [privileges](https://docs.coveo.com/en/228/), 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](https://docs.coveo.com/en/2120/).

**Example**

```json
{
  "statusCode": 401,
  "message": "Missing Authorization header or token is improperly formatted.",
  "errorCode": "UNAUTHORIZED"
}
```

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

**Example**

```json
{
  "statusCode": 403,
  "message": "Access denied. API key does not have sufficient privileges.",
  "errorCode": "FORBIDDEN"
}
```

**Cause**

Typically, this error occurs when you're [authenticating](https://docs.coveo.com/en/2120/) using an API key which doesn't have the [privilege](https://docs.coveo.com/en/228/) to execute [queries](https://docs.coveo.com/en/231/).

**Resolution**

Modify the API key accordingly, or create a new API key with the required [privilege](https://docs.coveo.com/en/228/).

## 404 NOT_FOUND

**Symptom**

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

**Example**

```json
{
  "statusCode": 404,
  "message": "The requested Search API endpoint does not exist.",
  "errorCode": "NOT_FOUND"
}
```

**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](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.

**Example**

```json
{
  "statusCode": 419,
  "message": "Search token has expired."
}
```

**Cause**

Typically, this error occurs when you're [authenticating](https://docs.coveo.com/en/2120/) using an expired [search token](https://docs.coveo.com/en/1346/).

**Resolution**

Try again [using a fresh search-token](https://docs.coveo.com/en/56#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.

**Example**

```json
{
  "statusCode": 429,
  "message": "Too many requests."
}
```

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

**Example**

```json
{
  "statusCode": 500,
  "message": "Facet search failed due to internal index issues.",
  "errorCode": "FACET_SEARCH_FAILURE"
}
```

**Cause**

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

**Resolution**

Contact [Coveo Support](https://connect.coveo.com/s/case/Case/Default).

## 503 ORGANIZATION_PAUSED

**Symptom**

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

**Example**

```json
{
  "statusCode": 503,
  "message": "The organization is paused due to inactivity.",
  "errorCode": "ORGANIZATION_PAUSED"
}
```

**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](https://connect.coveo.com/s/case/Case/Default).

## 503 SERVER_UNAVAILABLE

**Symptom**

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

**Example**

```json
{
  "statusCode": 503,
  "message": "The server is currently unavailable due to overload or index unavailability.",
  "errorCode": "SERVER_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](https://connect.coveo.com/s/case/Case/Default) 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](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/186/) services from the [Coveo Service Status](https://status.cloud.coveo.com/) page.