Sección 06

Errores

Cómo debe fallar su herramienta para que el agente reaccione bien.

Esta página no es una convención genérica: los seis valores de error_type son el contrato canónico que el runtime de Asixto ya consume hoy para decidir qué hace el agente (reintentar, quedarse en el paso, cambiar de flujo o escalar a un humano). Un valor fuera de esta lista se trata como UNKNOWN.

Forma del error

Un fallo de negocio no es un error de transporte: devuelva la respuesta de la herramienta con el error dentro, no un 500.

JSON

{
  "error": {
    "error_type": "NOT_FOUND",
    "user_message": "No encontré una cita con esos datos."
  }
}

Campo	Exigencia	Uso
`error_type`	DEBE	Uno de los seis valores de la tabla siguiente, exactamente con esa grafía. Determina la reacción del agente.
`user_message`	DEBE	Frase corta, en español neutro, sin jerga ni identificadores. El agente la parafrasea o la lee en voz alta.
`details`	PUEDE	Detalle técnico para su propia traza. No lo consumimos y no llega al modelo ni al usuario.

No añada otros campos esperando que el agente los interprete: no hay nada más en el contrato. En particular, no existe una marca de "reintentable": la decisión de reintentar la deriva el agente del error_type, según la tabla.

Los seis valores de `error_type`

`error_type`	Cuándo usarlo	Qué hace el agente
`NOT_FOUND`	La entidad no existe con los datos dados.	Vuelve al paso de identificación y pide verificar los datos.
`VALIDATION`	El dato viene mal formado, incumple una regla que el esquema no puede expresar, el estado no permite la operación o hay ambigüedad.	Pide la corrección sin avanzar de paso. Es el más útil y el que más va a usar.
`PERMISSION`	La operación no le corresponde a ese cliente, o la entidad no le pertenece.	Escala a un humano. Salvo en llamada telefónica: ahí el escalado no existe como acción y el agente solo puede ofrecer transferir.
`SYSTEM`	Fallo técnico transitorio: su dependencia no responde, timeout, 5xx.	Se disculpa y permite reintentar. Nunca dice que el dato no existe.
`BLOCKER`	El cliente tiene un impedimento que le prohíbe la operación: mora, suspensión, cuenta bloqueada.	Lo explica con tacto y cambia de flujo hacia facturación. Lea el aviso de abajo antes de usarlo.
`UNKNOWN`	Cualquier cosa no clasificada.	Ninguna reacción definida. Úselo como último recurso: en la práctica el agente improvisa con el `user_message`.

PERMISSION cubre dos cosas que en su sistema pueden ser distintas ("no tiene permiso" y "esa cita no es suya"): las dos deben terminar en escalado, así que van con el mismo valor.

Cuidado con BLOCKER. Es el único valor que cambia el flujo de la conversación hacia el escenario de facturación. Si ese escenario no está habilitado para su tenant, el agente pierde el resto del catálogo en esa conversación y se queda solo con lo básico. Úselo únicamente para impedimentos reales de cartera, y coordine con nosotros que el escenario de facturación esté activo. Para «este cliente no puede hacer esto por su estado», use VALIDATION.

Lo que NO es un error

Situación	Respuesta correcta
Búsqueda válida sin resultados	Éxito con lista vacía y `total: 0`. Ver el aviso de abajo.
El cliente pide una franja ocupada	`VALIDATION`, con las alternativas disponibles en la respuesta.
Dato ambiguo (varios candidatos)	`VALIDATION` y un `user_message` que pida precisar. Nunca elija por él.
Entidad en estado terminal (cita cancelada, oportunidad cerrada)	`VALIDATION`, y diga en el `user_message` cuál es el estado actual.
Su servidor está limitando por cuota	`SYSTEM`. Para el agente es un fallo transitorio, que es lo correcto.
Su herramienta tarda más de 30 s	No hay nada que devolver: el runtime ya cortó. Diseñe para no llegar ahí (página 07).

Catálogo vacío ≠ error. Es el error de integración más frecuente y el más caro. Si devuelve error cuando simplemente no hay resultados, el agente entra en la rama de fallo: reintenta, retrocede de paso o se disculpa por un problema técnico que no existe. Devuelva {"resultados": [], "total": 0} y déjelo hablar con naturalidad.

La distinción que más importa

Diagrama

❌  catálogo vacío  →  UNKNOWN / SYSTEM  →  "tengo un problema técnico" (falso)
❌  su BD caída     →  NOT_FOUND         →  "no tenemos ese producto"   (falso y grave)
✅  catálogo vacío  →  éxito, total 0    →  "no encontré ese producto"
✅  su BD caída     →  SYSTEM            →  "no puedo consultarlo ahora, ¿lo intentamos de nuevo?"

Colapsar los dos casos en un solo valor tiene una consecuencia concreta: el agente le dice a un cliente real que usted no vende algo que sí vende, y lo dice con total naturalidad.

Errores de protocolo

Reserve los fallos de transporte para lo que realmente lo es:

Situación	Respuesta correcta
Falta la credencial o es inválida	401 con `WWW-Authenticate`
Entrada que no cumple el `inputSchema`	Error de contrato del SDK (lo genera el propio SDK al validar)
Versión de protocolo no soportada	El error de versión previsto por el estándar, no un 500
Herramienta inexistente	Error de método del protocolo
Excepción no controlada	Capture y devuelva `error_type: "SYSTEM"`. Un 500 sin cuerpo deja al agente sin nada que decir

Reglas de redacción de `user_message`

Máximo una o dos frases. Se puede escuchar por teléfono.
Sin identificadores, códigos internos, nombres de tabla ni de sistema.
Sin culpar al usuario y sin disculpas largas: el agente pone el tono.
Sin instrucciones al modelo ("pide el documento otra vez"): eso lo decide el error_type.
Sin datos personales de terceros, aunque sea para desambiguar.