Gestion des erreurs

Chaque erreur d’un SDK Frontmail est une instance de FrontmailError (ou d’une sous-classe) avec :

Propriété	Signification
code	Identifiant stable, p. ex. invalid_template_params – voir Codes d’erreur
status	Statut HTTP, ou 0 pour les erreurs côté client
message	Description en anglais, destinée aux développeurs
docsUrl	Lien vers l’explication de ce code
details	Données supplémentaires – pour invalid_template_params, la liste des issues
retryAfter	Secondes, pour les erreurs de rate limit

Sous-classes

Classe	Quand
ValidationError	400 / 422 – corps ou paramètres invalides (details.issues)
AuthError	401, et 403 pour forbidden, origin_not_allowed, private_key_required
InsufficientCreditsError	402 – uniquement en mode reject
RateLimitError	429 après épuisement des nouvelles tentatives
BlockedError	Bloqué dans le navigateur par blockHeadless, blockList ou limitRate
NetworkError	Aucune réponse HTTP : hors ligne, DNS, CORS, délai dépassé (après les nouvelles tentatives)
FrontmailError	Tout le reste (p. ex. captcha_failed, recipient_suppressed, 5xx)

Exemple

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

try {
  const { status } = await send('svc_01J9…', 'tpl_contact', params);
  showSuccess(status === 'held' ? 'Bien reçu – nous le transmettrons sous peu.' : 'Merci !');
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.details?.issues ?? []) showFieldError(issue.param, issue.message);
  } else if (err instanceof NetworkError) {
    showError('Vous semblez être hors ligne. Veuillez réessayer.');
  } else if (err instanceof BlockedError) {
    showError('Veuillez patienter un instant avant de renvoyer.');
  } else if (err instanceof FrontmailError && err.code === 'captcha_failed') {
    resetTurnstile();
    showError('Veuillez confirmer que vous n’êtes pas un robot.');
  } else {
    showError('Désolé, le message n’a pas pu être envoyé.');
    console.error(err); // contient code et docsUrl
  }
}

Ce qu’il faut montrer aux utilisateurs

• held n’est pas une erreur – affichez une confirmation normale.
• Problèmes de validation : affichez-les à côté des champs (issue.param), idéalement avec votre propre texte traduit, choisi selon issue.code.
• Tout le reste : un message générique. N’affichez pas message tel quel aux utilisateurs finaux – il est rédigé pour les développeurs.
• Journalisez code, status et, le cas échéant, l’identifiant du message – ils accélèrent les demandes de support.

Les helpers React, React Native, Vue et Svelte ne lèvent jamais d’exception depuis send() ; ils placent l’erreur dans leur état error.