---
title: "Errores"
description: "La forma de todo error de la API de Qomni, cada campo que trae y qué hacer con cada código y estado HTTP."
version: "es"
---

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

# Errores

Todo error de la API de Qomni tiene la misma forma, definida una sola vez en
`contracts/shared/v1/components.yaml#/components/schemas/Error`. Decide por
`code`, muestra `message` y guarda `request_id`.

## Códigos

| Estado | `code` | Qué hacer |
|---|---|---|
| `401` | `api_key_missing` | Falta el header `Authorization`. Envía `Authorization: Bearer <key>`. |
| `401` | `api_key_malformed` | La clave no tiene la forma `sk_…` o su checksum no cuadra. Cópiala de nuevo. |
| `401` | `api_key_invalid` | La clave no existe o fue revocada. Crea otra. |
| `401` | `api_key_wrong_product` | La clave es de otro producto. Usa una clave de Agents. |
| `403` | `product_not_active` | El workspace no tiene Agents activo. Actívalo en **Ajustes**. |
| `404` | `not_found` | La ruta o el recurso no existen. |
| `404` | `host_moved` | El host es la dirección antigua de un producto (`agents.qomni.ai`), que ya no sirve páginas. Usa `https://app.qomni.ai/{workspace}/{producto}`. |
| `404` | `api_host_moved` | El host es la dirección antigua de la API (`agents-api.qomni.ai`). No redirige: `message` trae la URL base nueva, `https://api.qomni.ai/agents/v1`. Cambia la URL base de tu cliente. |
| `404` | `unknown_api` | El primer segmento de la ruta en `api.qomni.ai` no nombra ninguna API. Empieza la ruta por el producto y la versión (`/agents/v1/…`). |
| `405` | `method_not_allowed` | La ruta existe, pero no con ese método. |
| `410` | `product_host_moved` | Enviaste un `POST`, `PUT`, `PATCH` o `DELETE` a la dirección antigua de un producto (`agents.qomni.ai`). Esas direcciones sólo redirigen un `GET` o `HEAD` a `app.qomni.ai/{workspace}/{producto}`; envía la petición ahí. La API no pasa por esas direcciones: vive en `https://api.qomni.ai/agents/v1`. |
| `421` | `wrong_cell` | La clave es de otra celda. No ocurre con una clave creada por el workspace. |
| `422` | `validation_failed` | Un campo falta o no es válido. Corrige los campos de `fields`. Los campos desconocidos también se rechazan. |
| `429` | `rate_limited` | Superaste el límite. Espera los segundos de `Retry-After` y reintenta. Ver [Límites de uso](/es/concepts/rate-limits/). |
| `503` | `origin_unavailable` | La celda no respondió. No se hizo nada: reintenta con backoff. Ver [Idempotencia](/es/concepts/idempotency/). |

Cada operación de la referencia lista además los códigos propios de esa
operación, por ejemplo `demo_unavailable` al abrir una sesión del demo.

## Forma

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

| Campo | Tipo | Descripción |
|---|---|---|
| `code` | string, obligatorio | Estable. Es el valor con el que decide tu código. |
| `message` | string, obligatorio | Para personas. Puede cambiar en cualquier momento: nunca compares contra él. |
| `request_id` | string, obligatorio | Identifica la petición. Inclúyelo cuando escribas a soporte. |
| `fields` | objeto | Sólo en `validation_failed`: los mensajes de cada campo, por nombre. |

En el WebSocket de Agents, un error es un mensaje de tipo `error` con el mismo
objeto `{ code, message }` dentro.

## En tu código

Lee `code` y guarda `request_id`. Por ejemplo, al crear una llamada sin
destino la API responde `422` con el detalle de cada campo en `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/es/concepts/errors/index.mdx
