Gestione degli errori

Ogni errore di un SDK Frontmail è un’istanza di FrontmailError (o di una sua sottoclasse) con:

Proprietà	Significato
code	Identificatore stabile, ad es. invalid_template_params – vedi Codici di errore
status	Stato HTTP, oppure 0 per gli errori lato client
message	Descrizione in inglese, pensata per gli sviluppatori
docsUrl	Link alla spiegazione di questo codice
details	Dati aggiuntivi – per invalid_template_params l’elenco degli issues
retryAfter	Secondi, per gli errori di rate limit

Sottoclassi

Classe	Quando
ValidationError	400 / 422 – body o parametri non validi (details.issues)
AuthError	401, e 403 per forbidden, origin_not_allowed, private_key_required
InsufficientCreditsError	402 – solo in modalità reject
RateLimitError	429 dopo aver esaurito i tentativi
BlockedError	Bloccato nel browser da blockHeadless, blockList o limitRate
NetworkError	Nessuna risposta HTTP: offline, DNS, CORS, timeout (dopo i tentativi)
FrontmailError	Tutto il resto (ad es. captcha_failed, recipient_suppressed, 5xx)

Esempio

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

try {
  const { status } = await send('svc_01J9…', 'tpl_contact', params);
  showSuccess(status === 'held' ? 'Ricevuto – lo recapiteremo a breve.' : 'Grazie!');
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.details?.issues ?? []) showFieldError(issue.param, issue.message);
  } else if (err instanceof NetworkError) {
    showError('Sembra che tu sia offline. Riprova.');
  } else if (err instanceof BlockedError) {
    showError('Attendi un momento prima di inviare di nuovo.');
  } else if (err instanceof FrontmailError && err.code === 'captcha_failed') {
    resetTurnstile();
    showError('Conferma di non essere un robot.');
  } else {
    showError('Spiacenti, non è stato possibile inviare il messaggio.');
    console.error(err); // include code e docsUrl
  }
}

Cosa mostrare agli utenti

• held non è un errore – mostra una normale conferma.
• Problemi di validazione: mostrali accanto ai campi (issue.param), idealmente con un tuo testo tradotto in base a issue.code.
• Tutto il resto: un messaggio generico. Non mostrare message così com’è agli utenti finali – è scritto per gli sviluppatori.
• Registra nei log code, status e l’eventuale ID del messaggio – rendono le richieste di supporto molto più rapide.

Gli helper per React, React Native, Vue e Svelte non lanciano mai eccezioni da send(); mettono invece l’errore nel loro stato error.