Errores del flujo embebido

Taxonomía completa de los códigos de error que puede recibir tu integración embebida: qué significa cada uno, quién lo emite, si es terminal o reintentable, y qué hacer.

Cómo te llegan los errores

Hay dos canales, según la capa donde ocurre el error:

1. Excepción síncrona de AllSign.init() — errores de validación local del SDK (secret faltante, formato inválido, secret key en el browser). Se lanzan como AllSignError con un code estable.

2. Callback onExit con metadata.error.code — errores en tiempo de ejecución dentro del iframe (init contra el backend, firma, verificación de identidad). El iframe emite allsign:error y el SDK te lo entrega verbatim en onExit — el SDK no normaliza códigos, así que puedes recibir códigos que tu versión del SDK aún no cataloga.

import { AllSign, AllSignError, isRetryableError } from '@allsign/embedded';

try {
  const session = AllSign.init({
    clientSecret,
    onExit: (metadata) => {
      const code = metadata.error?.code;
      if (!code) return; // salida limpia (completada o cancelada por el firmante)
      console.error('Error embebido:', code, metadata.error?.message);
    },
  });
  session.modal();
} catch (e) {
  if (e instanceof AllSignError) {
    // Error de validación local — corrige tu integración
    console.error(e.code, e.message);
  }
}

Terminal vs reintentable

Cada código cae en una de dos clases, y la clase determina la recuperación:

• Reintentable (transitorio) — la falla es de infraestructura, no de la sesión. El mismo client_secret sigue siendo válido y re-intercambiable durante toda su ventana de 15 minutos: re-invoca AllSign.init con él (idealmente con backoff). Son reintentables: NETWORK_ERROR, BACKEND_UNREACHABLE, INVALID_BACKEND_RESPONSE, INTERNAL_ERROR, INIT_TIMEOUT y cualquier HTTP_5xx.

• Terminal — la sesión quedó inutilizable (expiró, se completó, se canceló, es inválida o está mal configurada). Reintentar con el mismo client_secret no puede funcionar. Recuperación: tu servidor crea una sesión nueva y tu frontend re-invoca init (ver Recuperación). Todo código que no esté en la lista reintentable — incluidos códigos desconocidos — es terminal.

Desde la versión 0.3.0 del SDK, los helpers isRetryableError(code) / isTerminalError(code) implementan exactamente esta clasificación (incluyendo el patrón HTTP_5xx):

import { isRetryableError, isTerminalError } from '@allsign/embedded';

isRetryableError('BACKEND_UNREACHABLE'); // true
isRetryableError('HTTP_503');            // true
isTerminalError('SESSION_EXPIRED');      // true
isTerminalError('CODIGO_FUTURO');        // true — default seguro

Catálogo completo

Recuperación

El patrón de recuperación es el mismo que usa Plaid Link: ante un error terminal, no "revivas" la sesión — crea una nueva. Las Signing Sessions son baratas de crear y el client_secret dura 15 minutos.

1. Error reintentable → re-invoca AllSign.init con el mismo client_secret (sigue siendo re-intercambiable dentro de su ventana de 15 min; el backend rota el token interno y devuelve uno fresco). Usa un backoff corto.
2. Error terminal → tu servidor crea una sesión nueva con POST /v2/signing-sessions (mismo document_id, mismo firmante) y tu frontend re-invoca init con el client_secret fresco.

import { AllSign, isRetryableError } from '@allsign/embedded';

function montarFirma(clientSecret) {
  const session = AllSign.init({
    clientSecret,
    onSuccess: (result) => actualizarUI(result),
    onExit: async (metadata) => {
      const code = metadata.error?.code;
      if (!code) return; // salida limpia — no hay nada que recuperar

      if (isRetryableError(code)) {
        // Transitorio: el MISMO client_secret sigue siendo válido
        setTimeout(() => montarFirma(clientSecret), 2000);
        return;
      }

      // Terminal: pide a TU backend una sesión NUEVA y re-monta
      const res = await fetch('/mi-api/signing-sessions', {
        method: 'POST',
        body: JSON.stringify({ documentId: miDocumentId }),
      });
      const { client_secret: fresco } = await res.json();
      montarFirma(fresco);
    },
  });
  session.modal();
}

Casos que NO debes reintentar en automático:

• SESSION_COMPLETED — ya está firmado; muéstralo como éxito.
• RATE_LIMITED — espera ~1 minuto; reintentar en loop solo alarga el bloqueo.
• SECRET_KEY_PASSED_AS_CLIENT_SECRET, ORIGIN_NOT_ALLOWED, ALLOWED_ORIGINS_REQUIRED, CSP_BLOCKED, NOT_EMBEDDED — son errores de configuración de tu integración; ningún reintento los arregla.
• VERIFICATION_FAILED — es un resultado de identidad del firmante; decide tu flujo de producto (reintento manual, revisión).

Reporte a soporte

Si un error persiste después de aplicar el patrón de recuperación, repórtalo con estos datos — aceleran el diagnóstico de días a minutos:

Canales: GitHub Issues del SDK para bugs del SDK, o tu canal de soporte de AllSign para errores de sesión/backend (incluye el sessionId — sin él no podemos rastrear la sesión).

Siguiente paso

• JS SDK Reference — API completa del SDK, incluidos isRetryableError / isTerminalError
• Eventos y Callbacks — onExit, onEvent y el shape de ExitMetadata
• Seguridad — allowed_origins, CSP y validación de sesiones