Gestión de errores

Todos los errores de un SDK de Frontmail son instancias de FrontmailError (o de una subclase) con:

Propiedad	Significado
code	Identificador estable, p. ej. invalid_template_params; consulta Códigos de error
status	Estado HTTP, o 0 para los errores del lado del cliente
message	Descripción en inglés, pensada para desarrolladores
docsUrl	Enlace a la explicación de este código
details	Datos adicionales; en invalid_template_params, la lista de issues
retryAfter	Segundos, en los errores de límite de solicitudes

Subclases

Clase	Cuándo
ValidationError	400 / 422: cuerpo o parámetros no válidos (details.issues)
AuthError	401, y 403 para forbidden, origin_not_allowed, private_key_required
InsufficientCreditsError	402: solo en el modo reject
RateLimitError	429 después de agotar los reintentos
BlockedError	Bloqueado en el navegador por blockHeadless, blockList o limitRate
NetworkError	Sin respuesta HTTP: sin conexión, DNS, CORS, tiempo de espera agotado (después de los reintentos)
FrontmailError	Todo lo demás (p. ej. captcha_failed, recipient_suppressed, 5xx)

Ejemplo

import { send, FrontmailError, ValidationError, NetworkError, BlockedError } from '@frontmail/browser';

try {
  const { status } = await send('svc_01J9…', 'tpl_contact', params);
  showSuccess(status === 'held' ? 'Recibido: lo entregaremos en breve.' : '¡Gracias!');
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.details?.issues ?? []) showFieldError(issue.param, issue.message);
  } else if (err instanceof NetworkError) {
    showError('Parece que no tienes conexión. Vuelve a intentarlo.');
  } else if (err instanceof BlockedError) {
    showError('Espera un momento antes de volver a enviar.');
  } else if (err instanceof FrontmailError && err.code === 'captcha_failed') {
    resetTurnstile();
    showError('Confirma que no eres un robot.');
  } else {
    showError('Lo sentimos, no se ha podido enviar el mensaje.');
    console.error(err); // incluye code y docsUrl
  }
}

Qué mostrar a los usuarios

• held no es un error: muestra una confirmación normal.
• Problemas de validación: muéstralos junto a los campos (issue.param), idealmente con tu propio texto traducido según issue.code.
• Todo lo demás: un mensaje genérico. No muestres message tal cual a los usuarios finales: está escrito para desarrolladores.
• Registra code, status y el ID del mensaje, si lo hay: agilizan mucho las solicitudes de soporte.

Los helpers de React, React Native, Vue y Svelte nunca lanzan errores desde send(); en su lugar, guardan el error en su estado error.