Manejo de Errores

El SDK lanza errores tipados que puedes capturar y manejar adecuadamente.

Códigos de error

Código	Estado HTTP	Descripción
VALIDATION_ERROR	400	Parámetros de petición inválidos
UNAUTHORIZED	401	Clave API inválida o ausente
FORBIDDEN	403	Permisos insuficientes
NOT_FOUND	404	El recurso no existe
RATE_LIMITED	429	Demasiadas peticiones
INTERNAL_ERROR	500	Error del servidor — reintentar con backoff

Manejo de errores

error-handling.ts

try {
  const session = await client.createSession({
    referenceId: 'user-12345',
  });
} catch (error) {
  if (error instanceof HeuristikError) {
    switch (error.code) {
      case 'VALIDATION_ERROR':
        console.error('Entrada inválida:', error.details);
        break;
      case 'RATE_LIMITED':
        console.warn('Límite de peticiones — reintentar en', error.retryAfter, 'segundos');
        break;
      case 'UNAUTHORIZED':
        console.error('Verifica tu clave API');
        break;
      default:
        console.error('Error inesperado:', error.message);
    }
  }
}

No ignores los errores

Siempre envuelve las llamadas al SDK en bloques try/catch. Los errores no manejados pueden hacer fallar tu aplicación o dejar verificaciones en un estado inconsistente.

Estrategia de reintentos

Para errores transitorios (429, 500, 503), implementa backoff exponencial:

retry.ts

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
  throw new Error('Unreachable');
}

Idempotencia

Usa referenceId como clave de idempotencia. Si reintentas una llamada a createSession con el mismo referenceId, la API devuelve la sesión existente en lugar de crear un duplicado.