---
title: "Erros"
description: "A forma de todo erro da API da Qomni, cada campo que ele traz e o que fazer com cada código e status HTTP."
version: "pt-br"
---

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

# Erros

Todo erro da API da Qomni tem a mesma forma, definida uma única vez em
`contracts/shared/v1/components.yaml#/components/schemas/Error`. Decida por
`code`, mostre `message` e guarde `request_id`.

## Códigos

| Status | `code` | O que fazer |
|---|---|---|
| `401` | `api_key_missing` | Falta o header `Authorization`. Envie `Authorization: Bearer <key>`. |
| `401` | `api_key_malformed` | A chave não tem a forma `sk_…` ou seu checksum não bate. Copie-a de novo. |
| `401` | `api_key_invalid` | A chave não existe ou foi revogada. Crie outra. |
| `401` | `api_key_wrong_product` | A chave é de outro produto. Use uma chave de Agents. |
| `403` | `product_not_active` | O workspace não tem o Agents ativo. Ative-o em **Configurações**. |
| `404` | `not_found` | A rota ou o recurso não existem. |
| `404` | `host_moved` | O host é o endereço antigo de um produto (`agents.qomni.ai`), que já não serve páginas. Use `https://app.qomni.ai/{workspace}/{producto}`. |
| `404` | `api_host_moved` | O host é o endereço antigo da API (`agents-api.qomni.ai`). Ele não redireciona: `message` traz a nova URL base, `https://api.qomni.ai/agents/v1`. Troque a URL base do seu cliente. |
| `404` | `unknown_api` | O primeiro segmento da rota em `api.qomni.ai` não nomeia nenhuma API. Comece a rota pelo produto e pela versão (`/agents/v1/…`). |
| `405` | `method_not_allowed` | A rota existe, mas não com esse método. |
| `410` | `product_host_moved` | Você enviou um `POST`, `PUT`, `PATCH` ou `DELETE` ao endereço antigo de um produto (`agents.qomni.ai`). Esses endereços só redirecionam um `GET` ou `HEAD` para `app.qomni.ai/{workspace}/{producto}`; envie a requisição para lá. A API não passa por esses endereços: ela vive em `https://api.qomni.ai/agents/v1`. |
| `421` | `wrong_cell` | A chave é de outra célula. Não acontece com uma chave criada pelo workspace. |
| `422` | `validation_failed` | Um campo falta ou não é válido. Corrija os campos de `fields`. Campos desconhecidos também são rejeitados. |
| `429` | `rate_limited` | Você superou o limite. Espere os segundos de `Retry-After` e tente de novo. Veja [Limites de uso](/pt-br/concepts/rate-limits/). |
| `503` | `origin_unavailable` | A célula não respondeu. Nada foi feito: tente de novo com backoff. Veja [Idempotência](/pt-br/concepts/idempotency/). |

Cada operação da referência lista ainda os códigos próprios dessa
operação, por exemplo `demo_unavailable` ao abrir uma sessão do demo.

## Forma

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

| Campo | Tipo | Descrição |
|---|---|---|
| `code` | string, obrigatório | Estável. É o valor com que seu código decide. |
| `message` | string, obrigatório | Para pessoas. Pode mudar a qualquer momento: nunca compare com ele. |
| `request_id` | string, obrigatório | Identifica a requisição. Inclua-o quando escrever ao suporte. |
| `fields` | objeto | Só em `validation_failed`: as mensagens de cada campo, por nome. |

No WebSocket do Agents, um erro é uma mensagem do tipo `error` com o mesmo
objeto `{ code, message }` dentro.

## No seu código

Leia `code` e guarde `request_id`. Por exemplo, ao criar uma chamada sem
destino a API responde `422` com o detalhe de cada campo em `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/pt-br/concepts/errors/index.mdx
