> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/getting-started/error-codes.md).

# Error codes

Reference for identifying API failures and choosing the right recovery action.

Treat HTTP status, response body, and, when present, statement status as separate signals.

| Code  | Meaning             | Common cause                                                                                  | Client action                                                    |
| ----- | ------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `400` | Bad Request         | Invalid SQL, unsupported query shape, invalid semantic member, or invalid columns projection. | Correct the request; do not retry unchanged.                     |
| `401` | Unauthorized        | Missing, malformed, invalid, or expired Bearer token.                                         | Refresh the token and retry once.                                |
| `403` | Forbidden           | Valid identity lacks access or ownership.                                                     | Request access or use an authorized identity.                    |
| `404` | Not Found           | Resource, statement, metric, perspective, or result is absent.                                | Verify the ID/name; fetch results only after `SUCCESS`.          |
| `406` | Not Acceptable      | Unsupported result format.                                                                    | Use `json`, `yaml`, `csv`, or `parquet`.                         |
| `409` | Conflict            | Perspective slug is already taken.                                                            | Use one of the suggested slugs or choose another.                |
| `422` | Validation Error    | Required field missing, empty SQL, invalid type, or malformed request body.                   | Fix the body against the endpoint schema.                        |
| `429` | Too Many Requests   | A platform or gateway rate limit was exceeded.                                                | Respect `Retry-After` and back off.                              |
| `500` | Internal Error      | Unexpected server or result-processing failure.                                               | Retry only if the operation is safe; report persistent failures. |
| `501` | Not Implemented     | A configured backend does not support the requested operation.                                | Use a supported backend or contact the owner.                    |
| `502` | Upstream Error      | Semantic transpiler or object store failed.                                                   | Simplify/validate the query; retry transient upstream failures.  |
| `503` | Service Unavailable | Worker, transpiler, or object store is temporarily unavailable.                               | Back off and retry.                                              |

## Async statement failures

A query can be accepted with HTTP `202` and fail later. Poll until a terminal status:

* `SUCCESS`: fetch the result.
* `FAILED`: inspect `error`; no result artifact exists.

Do not treat `202 Accepted` as a completed query.

## GraphQL errors

GraphQL validation and resolver failures can return HTTP `200` with a top-level `errors` array. A GraphQL client must inspect both HTTP status and body:

```json
{
  "errors": [
    {
      "message": "Cannot query field 'unknown_field' on type 'OrdersMembers'."
    }
  ]
}
```

Long GraphQL queries can return `202` with `Retry-After`; this is not an error. Retry the identical request after the indicated interval or follow the statement link in `extensions._links`.

## Next step

With access, requests, and failure handling covered, continue to [Querying Data Products](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products.md) to choose a query method.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/getting-started/error-codes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
