---
title: "Errors"
description: "The shape of every Qomni API error, each field it carries and what to do with each code and HTTP status."
version: "en"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

Every error of the Qomni API has the same shape, defined once in `contracts/shared/v1/components.yaml#/components/schemas/Error`.
Decide by `code`, show `message` and store `request_id`.

## Codes

| Status | `code` | What to do |
|---|---|---|
| `401` | `api_key_missing` | The `Authorization` header is missing. Send `Authorization: Bearer <key>`. |
| `401` | `api_key_malformed` | The key does not have the form `sk_…` or its checksum does not match. Copy it again. |
| `401` | `api_key_invalid` | The key does not exist or was revoked. Create another one. |
| `401` | `api_key_wrong_product` | The key belongs to another product. Use an Agents key. |
| `403` | `product_not_active` | The workspace does not have Agents enabled. Enable it in **Settings**. |
| `404` | `not_found` | The route or the resource does not exist. |
| `404` | `host_moved` | The host is a product's old address (`agents.qomni.ai`), which no longer serves pages. Use `https://app.qomni.ai/{workspace}/{producto}`. |
| `404` | `api_host_moved` | The host is the API's old address (`agents-api.qomni.ai`). It does not redirect: `message` carries the new base URL, `https://api.qomni.ai/agents/v1`. Change your client's base URL. |
| `404` | `unknown_api` | The first segment of the path on `api.qomni.ai` does not name any API. Start the path with the product and the version (`/agents/v1/…`). |
| `405` | `method_not_allowed` | The route exists, but not with that method. |
| `410` | `product_host_moved` | You sent a `POST`, `PUT`, `PATCH` or `DELETE` to a product's old address (`agents.qomni.ai`). Those addresses only redirect a `GET` or `HEAD` to `app.qomni.ai/{workspace}/{producto}`; send the request there. The API does not go through those addresses: it lives at `https://api.qomni.ai/agents/v1`. |
| `421` | `wrong_cell` | The key belongs to another cell. It does not happen with a key created by the workspace. |
| `422` | `validation_failed` | A field is missing or invalid. Fix the fields in `fields`. Unknown fields are rejected too. |
| `429` | `rate_limited` | You exceeded the limit. Wait the seconds in `Retry-After` and retry. See [Rate limits](/concepts/rate-limits/). |
| `503` | `origin_unavailable` | The cell did not respond. Nothing was done: retry with backoff. See [Idempotency](/concepts/idempotency/). |

Each operation in the reference also lists the codes specific to that
operation, for example `demo_unavailable` when opening a demo session.

## Shape

```json
{
  "error": {
    "code": "api_key_wrong_product",
    "message": "This key is for another product.",
    "request_id": "req_01m40n2ansfhj861etnav19mbp"
  }
}
```

| Field | Type | Description |
|---|---|---|
| `code` | string, required | Stable. It is the value your code decides on. |
| `message` | string, required | For people. It can change at any time: never compare against it. |
| `request_id` | string, required | Identifies the request. Include it when you write to support. |
| `fields` | object | Only in `validation_failed`: the messages for each field, by name. |

On the Agents WebSocket, an error is a message of type `error` with the same
`{ code, message }` object inside.

## In your code

Read `code` and store `request_id`. For example, when you create a call without a
destination the API responds `422` with the detail of each field in `fields`:

```python
if not response.ok:
    error = response.json()["error"]
    if error["code"] == "validation_failed":
        print(error["fields"])
    raise SystemExit(f"{error['code']} ({error['request_id']})")
```

```typescript
if (!response.ok) {
  const { error } = await response.json();
  if (error.code === "validation_failed") console.log(error.fields);
  throw new Error(`${error.code} (${error.request_id})`);
}
```

```json title="422 Unprocessable Content"
{
  "error": {
    "code": "validation_failed",
    "message": "The to field is required.",
    "request_id": "req_52abfa8dd5144eee89f62f0c653310e5",
    "fields": {
      "to": ["The to field is required."]
    }
  }
}
```

Source: https://docs.qomni.ai/concepts/errors/index.mdx
