Errores, límites y puesta en producción

Interpretar los códigos HTTP

Código	Causa habitual	Acción
400	Datos inválidos o agente inexistente	Corrige la petición; no reintentes sin cambios
401	Token vencido o revocado; licencia de widget inválida	Distingue el mecanismo de autenticación y revisa sus credenciales
402	Licencia de instalación no vigente	Escala al administrador de AGOS
403	Permiso faltante o función no habilitada	Revisa rol y alcance de licencia
404	Recurso ausente, widget no publicado o audio deshabilitado	Verifica ruta, identificador y configuración
409	Clave o identificador duplicado	Consulta el recurso antes de intentar crearlo de nuevo
413	Archivo demasiado grande	Reduce el tamaño según el límite documentado
429	Ráfaga o cuota agotada	Respeta Retry-After cuando exista y distingue el tipo de cuota
503	Cola llena o servicio no disponible	Reintenta de forma acotada, con espera exponencial y variación aleatoria

Leer el cuerpo sin asumir un único formato

La mayoría de los errores usa { "error": "..." }, pero también hay texto plano, arreglos de mensajes de Identity y application/problem+json con campos de validación en errors.

Revisa el estado HTTP antes de deserializar una respuesta de éxito. Conserva el código y un diagnóstico seguro; no registres credenciales ni conversaciones completas por defecto.

Respetar límites

Recurso	Límite documentado
Autenticación	10 peticiones/minuto por IP
Chat autenticado	20 peticiones/minuto por usuario por defecto, configurable
Widget público: chat y audio	20 peticiones/minuto por IP
Audio autenticado	10 peticiones/minuto por usuario
Documentos	Hasta 50 MB
Audio	Hasta 15 MB
Imágenes de chat	Hasta 5 MB

La cuota diaria del chat depende del plan del usuario. La cuota mensual del widget pertenece a la licencia de uso. El exceso de maxInputChars se recorta: valida en tu interfaz si necesitas evitar que se pierda parte de la pregunta.

Reintentos sin duplicar operaciones

No repitas automáticamente una creación o un envío cuyo resultado es incierto. Una desconexión puede ocurrir después de que el servidor haya procesado la operación. El contrato no documenta una clave de idempotencia universal.

Para lecturas, usa reintentos limitados con un tiempo máximo. Para escrituras, verifica si la operación se realizó antes de repetirla. Un 403 o un 402 no se soluciona reintentando.

Chat en streaming

POST /api/chat/stream devuelve Server-Sent Events. El primer evento comunica la cola, luego llegan fragmentos de texto y finalmente [DONE].

data: {"event":"queue_position","length":0}

data: Para registrar

data:  una devolución...

data: [DONE]

Usa un cliente SSE probado que admita POST y encabezados Bearer. No asumas que cada bloque de red corresponde a un evento completo. El streaming no devuelve messageId ni sources; usa el chat sin streaming si necesitas esos campos.

Lista de verificación de producción

• Usuario dedicado y rol de mínimo privilegio.
• HTTPS y secretos protegidos en el backend.
• Renovación de token sin bucles de login.
• Manejo diferenciado de 401, 402, 403, 429 y 503.
• Timeouts y cancelación acordes con la espera de inferencia.
• Markdown de respuestas sanitizado antes de mostrar HTML.
• Control de cuota por usuario y licencia, sin registrar secretos.
• Prueba del agente, sus fuentes y los permisos en un entorno autorizado.
• Comprobación de versión y contrato con el operador antes de liberar.

El endpoint /health es interno: no se expone a través del panel. Coordina la monitorización con el operador; no presupongas una URL pública de salud.