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. |
503 |
origin_unavailable |
La celda no respondió. No se hizo nada: reintenta con backoff. Ver Idempotencia. |
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
{
"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:
if not response.ok:
error = response.json()["error"]
if error["code"] == "validation_failed":
print(error["fields"])
raise SystemExit(f"{error['code']} ({error['request_id']})")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})`);
}{
"error": {
"code": "validation_failed",
"message": "The to field is required.",
"request_id": "req_52abfa8dd5144eee89f62f0c653310e5",
"fields": {
"to": ["The to field is required."]
}
}
}