> For the complete documentation index, see [llms.txt](https://docs.e6data.com/query-engine/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.e6data.com/query-engine/reference/error-codes/rest-api.md).

# REST API errors

Error codes returned by the e6data REST API, what they mean, and how to fix them.

Errors returned by the [REST API](/query-engine/developers/connecting-to-the-engine/rest-api-for-sql.md) follow a consistent format:

```json
{
  "error": {
    "code": "QUERY_TIMEOUT",
    "message": "Query exceeded the configured timeout",
    "details": { ... }
  }
}
```

This page lists the codes you may encounter and how to handle them.

## Authentication errors (HTTP 401, 403)

| Code                | Meaning                         | Fix                              |
| ------------------- | ------------------------------- | -------------------------------- |
| `UNAUTHENTICATED`   | No or invalid token             | Check the `Authorization` header |
| `TOKEN_EXPIRED`     | Token has expired               | Generate a new token             |
| `TOKEN_REVOKED`     | Token was revoked               | Generate a new token             |
| `PERMISSION_DENIED` | Token can't perform this action | Check the token's role/scope     |

## Request errors (HTTP 400)

| Code                | Meaning                                                      | Fix                                       |
| ------------------- | ------------------------------------------------------------ | ----------------------------------------- |
| `INVALID_REQUEST`   | Request body is malformed JSON or missing required fields    | Check the request format                  |
| `INVALID_QUERY`     | SQL has a syntax error                                       | Fix the SQL                               |
| `CLUSTER_NOT_FOUND` | Named cluster doesn't exist                                  | Check the cluster name                    |
| `CATALOG_NOT_FOUND` | Named catalog doesn't exist or isn't attached to the cluster | Check catalog name and cluster attachment |
| `SCHEMA_NOT_FOUND`  | Schema isn't in the catalog                                  | Refresh the catalog or check the name     |
| `TABLE_NOT_FOUND`   | Table doesn't exist in the schema                            | Check the table name                      |
| `INVALID_PARAMETER` | Query parameter binding failed                               | Check parameter types and names           |

## Query lifecycle errors

| Code               | Meaning                                  | What it means                                    |
| ------------------ | ---------------------------------------- | ------------------------------------------------ |
| `QUERY_CANCELLED`  | Query was cancelled via DELETE           | Expected after a DELETE call                     |
| `QUERY_TIMEOUT`    | Query exceeded the configured timeout    | Either tune the query or raise the timeout       |
| `QUERY_FAILED`     | Query failed during execution            | Read `details` for the underlying error          |
| `RESULT_EXPIRED`   | Query results no longer available        | Results retention typically 24h; rerun the query |
| `RESULT_TOO_LARGE` | Result set exceeds the max response size | Use pagination or streaming                      |

## Resource errors (HTTP 503)

| Code                   | Meaning                                 | Fix                                                       |
| ---------------------- | --------------------------------------- | --------------------------------------------------------- |
| `CLUSTER_SUSPENDED`    | Cluster is suspended                    | Will auto-resume if configured; otherwise resume manually |
| `CLUSTER_PROVISIONING` | Cluster is being created                | Wait for cluster to become Running                        |
| `CLUSTER_UNAVAILABLE`  | Cluster has an error preventing queries | Check Compute Plane → cluster status                      |

## Rate limiting (HTTP 429)

| Code               | Meaning                                     | Fix                                             |
| ------------------ | ------------------------------------------- | ----------------------------------------------- |
| `RATE_LIMITED`     | Too many requests                           | Honor `Retry-After` header; reduce request rate |
| `CONCURRENT_LIMIT` | Too many concurrent queries on this cluster | Wait or increase cluster size                   |

## Server errors (HTTP 5xx)

| Code                  | Meaning                            | Fix                                                     |
| --------------------- | ---------------------------------- | ------------------------------------------------------- |
| `INTERNAL_ERROR`      | Unexpected server error            | Retry; if persistent, contact support with the Query ID |
| `SERVICE_UNAVAILABLE` | Backend is temporarily unavailable | Retry with backoff                                      |

## Error handling pattern

A robust client handles these categories distinctly:

```python
import requests
import time

def call_with_retry(method, url, **kwargs):
    backoff = 1
    for attempt in range(5):
        r = requests.request(method, url, **kwargs)
        
        if r.status_code == 200:
            return r.json()
        
        error = r.json().get("error", {})
        code = error.get("code")
        
        # Retry transient errors
        if r.status_code in (429, 503) or code in ("INTERNAL_ERROR", "SERVICE_UNAVAILABLE"):
            retry_after = int(r.headers.get("Retry-After", backoff))
            time.sleep(retry_after)
            backoff *= 2
            continue
        
        # Don't retry permanent errors
        raise RuntimeError(f"{r.status_code} {code}: {error.get('message')}")
    
    raise RuntimeError("Exhausted retries")
```

## See also

* [REST API overview](/query-engine/developers/connecting-to-the-engine/rest-api-for-sql.md)
* [Error codes overview](/query-engine/reference/error-codes.md)
* [Cluster errors](/query-engine/reference/error-codes/cluster.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.e6data.com/query-engine/reference/error-codes/rest-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.