Eventos y errores - Thaliq Docs

Eventos del SDK

El SDK emite eventos globales que puedes escuchar para monitorear el estado:

// Error no manejado
thaliq.on('error', (error) => {
  console.error('Error:', error.message);
});

// Rate limit alcanzado
thaliq.on('rateLimit', (info) => {
  console.warn(`Rate limit. Retry en ${info.retryAfter}s`);
});

// Reintento automatico
thaliq.on('retry', (attempt, error, delayMs) => {
  console.warn(`Retry #${attempt} en ${delayMs}ms: ${error.message}`);
});

// Stream iniciado
thaliq.on('stream.start', (conversationId) => {
  console.log('Stream iniciado:', conversationId);
});

// Stream completado
thaliq.on('stream.end', (conversationId) => {
  console.log('Stream completado:', conversationId);
});

// Usuario identificado
thaliq.on('identify', (userId) => {
  console.log('Identificado:', userId);
});

// Estado limpiado
thaliq.on('reset', () => {
  console.log('Reset');
});

Metodos

Metodo	Descripcion
`on(event, handler)`	Registra un listener
`off(event, handler)`	Elimina un listener
`once(event, handler)`	Listener que se ejecuta una sola vez

Tabla de eventos

Evento	Handler	Cuando se emite
`error`	`(error: ThaliqError) => void`	Error no manejado
`rateLimit`	`(error: ThaliqError & { retryAfter }) => void`	Rate limit alcanzado
`retry`	`(attempt, error, delayMs) => void`	Antes de un reintento automatico
`stream.start`	`(conversationId) => void`	Stream SSE iniciado
`stream.end`	`(conversationId) => void`	Stream SSE finalizado
`identify`	`(userId: string) => void`	`identify()` llamado
`reset`	`() => void`	`reset()` llamado

Eventos SSE del stream

Al consumir un stream con for await, cada evento tiene un campo type que identifica su contenido. La tabla completa de tipos:

Eventos de contenido

Tipo	Descripcion	Campos
`meta`	Metadata inicial	`conversationId: string`
`status`	Estado del agente	`text: string`
`content.delta`	Fragmento de texto	`delta: string`

Eventos de tools

Tipo	Descripcion	Campos
`tool.start`	Tool comienza a ejecutarse	`tool: string`
`tool.end`	Tool termino	`tool: string`, `success: boolean`

Eventos interactivos

Tipo	Descripcion	Campos
`action`	Accion HITL requerida	`action: PendingAction`
`handoff`	Escalado a agente humano	`message: string`, `agentName?: string`, `reason?: string`

Eventos de finalizacion

Tipo	Descripcion	Campos
`response.completed`	Respuesta completa	`message`, `conversationId`, `insights[]`, `metadata`
`message_stop`	Generacion finalizada	`model: string`, `usage: { inputTokens, outputTokens }`

Eventos de error y control

Tipo	Descripcion	Campos
`rate_limit`	Rate limit excedido	`message: string`, `retryAfter: number`
`error`	Error durante el stream	`message: string`
`keepalive`	Ping para mantener conexion	`ts: number`

Ejemplo completo de manejo de eventos

const stream = thaliq.agent.stream('Analiza los datos');

for await (const event of stream) {
  switch (event.type) {
    case 'meta':
      console.log('Conversacion:', event.conversationId);
      break;

    case 'status':
      showSpinner(event.text);
      break;

    case 'content.delta':
      appendText(event.delta);
      break;

    case 'tool.start':
      showToolIndicator(event.tool);
      break;

    case 'tool.end':
      hideToolIndicator(event.tool, event.success);
      break;

    case 'action':
      await handleAction(event.action);
      break;

    case 'handoff':
      showHandoffNotice(event.message, event.agentName);
      break;

    case 'response.completed':
      showInsights(event.insights);
      saveMessageId(event.metadata?.messageId); // Para feedback
      break;

    case 'rate_limit':
      showRetryCountdown(event.retryAfter);
      break;

    case 'error':
      showError(event.message);
      break;
  }
}

Manejo de errores

El SDK expone errores tipados para un manejo granular:

import { ThaliqError, RateLimitError, AuthError } from '@thaliq/sdk';

try {
  const response = await thaliq.agent.chat('Hola');
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limit. Retry en ${error.retryAfter}s`);
  } else if (error instanceof AuthError) {
    console.log('API Key invalida o feature no disponible');
  } else if (error instanceof ThaliqError) {
    console.log(`Error ${error.status}: ${error.message}`);
  }
}

Clases de error

Clase	HTTP Status	Descripcion
`ThaliqError`	Base	Error base del SDK
`AuthError`	401 / 403	API Key invalida o plan insuficiente
`RateLimitError`	429	Rate limit alcanzado (incluye `retryAfter`)
`ValidationError`	400	Request invalido (ej: falta apiKey)
`ServiceError`	503	Servicio no disponible
`StreamError`	—	Error durante streaming SSE
`TimeoutError`	—	Request timeout (configurable)
`ConnectionError`	—	Error de red

Propiedades de ThaliqError

class ThaliqError extends Error {
  message: string;      // Descripcion del error
  code: ErrorCode;      // Codigo unico (ej: 'AUTH_ERROR')
  status?: number;      // HTTP status (si aplica)
  retryable: boolean;   // Si se puede reintentar
}

Codigos de error

Codigo	Descripcion
`AUTH_ERROR`	Autenticacion fallida
`RATE_LIMIT`	Rate limit excedido
`VALIDATION_ERROR`	Request invalido
`SERVICE_ERROR`	Servicio no disponible
`STREAM_ERROR`	Error en streaming
`TIMEOUT_ERROR`	Timeout de request
`CONNECTION_ERROR`	Error de conexion
`UNKNOWN_ERROR`	Error no clasificado

RateLimitError

class RateLimitError extends ThaliqError {
  retryAfter?: number;  // Segundos para esperar
}

StreamError

Error especifico del streaming. Se lanza cuando:

El servidor envia un evento de error
Se intenta consumir un stream mas de una vez
El rate limit se excede durante el stream

try {
  for await (const event of stream) { /* ... */ }
} catch (error) {
  if (error instanceof StreamError) {
    console.log('Error de stream:', error.message);
  }
}

Errores en SSE vs excepciones

Hay dos formas en que pueden llegar errores durante streaming:

Mecanismo	Cuando	Como manejarlo
Evento `error`	El agente emite un error controlado	`if (event.type === 'error')` dentro del loop
Evento `rate_limit`	Se excedio el rate limit del tenant	`if (event.type === 'rate_limit')` dentro del loop
Excepcion `StreamError`	Error de red, stream corrupto	`try/catch` alrededor del `for await`
Excepcion `RateLimitError`	Rate limit en `chat()` (sin stream)	`try/catch` alrededor de `chat()`

try {
  for await (const event of stream) {
    if (event.type === 'error') {
      // Error controlado del agente
      console.error('Agent error:', event.message);
    }
    if (event.type === 'rate_limit') {
      // Rate limit — esperar y reintentar
      console.warn(`Rate limit. Espera ${event.retryAfter}s`);
    }
  }
} catch (error) {
  // Error de red, stream corrupto, o doble consumo
  if (error instanceof StreamError) {
    console.error('Stream error:', error.message);
  }
}

Imports

Todos los errores se importan directamente desde el SDK:

import {
  ThaliqError,
  AuthError,
  RateLimitError,
  ValidationError,
  ServiceError,
  StreamError,
  TimeoutError,
  ConnectionError,
} from '@thaliq/sdk';

​Eventos del SDK

​Metodos

​Tabla de eventos

​Eventos SSE del stream

​Eventos de contenido

​Eventos de tools

​Eventos interactivos

​Eventos de finalizacion

​Eventos de error y control

​Ejemplo completo de manejo de eventos

​Manejo de errores

​Clases de error

​Propiedades de ThaliqError

​Codigos de error

​RateLimitError

​StreamError

​Errores en SSE vs excepciones

​Imports