Errores y Troubleshooting

Reference Guide

Guía exhaustiva de clases de error tipadas en @caerus-dev/sdk, códigos de estado gRPC/HTTP asociados y estrategias recomendadas de mitigación.

Catálogo de Excepciones del SDK

El SDK mapea las respuestas binarias de error de gRPC a clases de excepción estándar de JavaScript / TypeScript:

Clase de Error	Código gRPC	Causa Principal
ConflictError	FAILED_PRECONDITION / 409	El recurso ya está retenido por otro usuario o sin stock disponible.
ValidationError	INVALID_ARGUMENT	La plantilla exige clave de idempotencia (`reason === 'IDEMPOTENCY_KEY_REQUIRED'`) o los parámetros son inválidos.
ResourceNotFoundError	NOT_FOUND / 404	El recurso, plantilla o holder especificado no existe o fue borrado lógicamente.
AuthenticationError	UNAUTHENTICATED	API Key inválida, revocada o no correspondiente al entorno.
TimeoutError	DEADLINE_EXCEEDED	La operación excedió el tiempo límite configurado en `timeoutMs`.

Manejo de `ConflictError`

Ocurre cuando intentas un take() sobre un recurso unitario ya tomado o cuando un recurso con cupo no tiene saldo suficiente:

manejo-conflicto.tstypescript

import { ConflictError } from '@caerus-dev/sdk';
 
try {
  const holder = await caerus.unitary('butaca_A1').take();
  // Continuar flujo de compra
} catch (error) {
  if (error instanceof ConflictError) {
    console.warn('Asiento ocupado:', error.message);
    // Informar amistosamente al frontend para que el usuario elija otra butaca
  } else {
    throw error;
  }
}

Manejo de `ValidationError` (Idempotencia)

Ocurre cuando una plantilla tiene activada la opción Idempotencia y se envía una solicitud sin idempotencyKey (donde error.reason === 'IDEMPOTENCY_KEY_REQUIRED'), o cuando se envían argumentos que no superan las validaciones:

manejo-idempotencia.tstypescript

import { ValidationError } from '@caerus-dev/sdk';
 
try {
  // Envía siempre una clave idempotente única asociada a la operación del usuario
  const holder = await caerus.unitary('butaca_A1').take({
    idempotencyKey: `req_${orderId}`,
  });
} catch (error) {
  if (error instanceof ValidationError && error.reason === 'IDEMPOTENCY_KEY_REQUIRED') {
    console.error('Clave de idempotencia requerida:', error.message);
  } else {
    throw error;
  }
}

Manejo de `ResourceNotFoundError` (404)

Se produce cuando el recurso, la plantilla asociada o el holderId no existen en el entorno consultado o fueron eliminados:

manejo-not-found.tstypescript

import { ResourceNotFoundError } from '@caerus-dev/sdk';
 
try {
  await caerus.confirm(holderId);
} catch (error) {
  if (error instanceof ResourceNotFoundError) {
    console.error('Holder o recurso no encontrado:', error.message);
    // Notificar al cliente que la reserva no existe o ya caducó
  } else {
    throw error;
  }
}

Troubleshooting Frecuente

1. "OpenSSL: wrong version number" al conectar localmente

Causa: El SDK encripta por defecto mediante TLS. Si tu motor local corre en localhost:9090 sin certificado SSL, debes especificar tls: false en las opciones del cliente.

2. "Invalid format in endpoint"

Causa: Se colocó https:// o una ruta (ej: localhost:9090/sre). Caerus utiliza gRPC; el endpoint solo debe tener la forma host:puerto (ej: localhost:9090).

3. ¿Por qué mi holder cambió de PENDING a EXPIRED?

Causa: El tiempo de vida otorgado en ttlSeconds transcurrió sin que tu backend llamara a caerus.confirm(holder.id). El sweeper de Caerus restauró el stock de forma automática.