Fehlerbehandlung

Jeder Fehler eines Frontmail-SDK ist eine Instanz von FrontmailError (oder einer Unterklasse) mit:

Eigenschaft	Bedeutung
code	Stabiler Bezeichner, z. B. invalid_template_params – siehe Fehlercodes
status	HTTP-Status oder 0 bei Fehlern auf Clientseite
message	Englische Beschreibung für Entwickler
docsUrl	Link zur Erklärung dieses Codes
details	Zusatzdaten – bei invalid_template_params die Liste issues
retryAfter	Sekunden, bei Rate-Limit-Fehlern

Unterklassen

Klasse	Wann
ValidationError	400 / 422 – ungültiger Body oder ungültige Parameter (details.issues)
AuthError	401 sowie 403 bei forbidden, origin_not_allowed, private_key_required
InsufficientCreditsError	402 – nur im Modus reject
RateLimitError	429, nachdem alle Wiederholungen aufgebraucht sind
BlockedError	Im Browser durch blockHeadless, blockList oder limitRate blockiert
NetworkError	Keine HTTP-Antwort: offline, DNS, CORS, Timeout (nach den Wiederholungen)
FrontmailError	Alles andere (z. B. captcha_failed, recipient_suppressed, 5xx)

Beispiel

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

try {
  const { status } = await send('svc_01J9…', 'tpl_contact', params);
  showSuccess(status === 'held' ? 'Erhalten – wir stellen sie in Kürze zu.' : 'Vielen Dank!');
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.details?.issues ?? []) showFieldError(issue.param, issue.message);
  } else if (err instanceof NetworkError) {
    showError('Sie scheinen offline zu sein. Bitte versuchen Sie es erneut.');
  } else if (err instanceof BlockedError) {
    showError('Bitte warten Sie einen Moment, bevor Sie erneut senden.');
  } else if (err instanceof FrontmailError && err.code === 'captcha_failed') {
    resetTurnstile();
    showError('Bitte bestätigen Sie, dass Sie kein Roboter sind.');
  } else {
    showError('Leider konnte die Nachricht nicht gesendet werden.');
    console.error(err); // enthält code und docsUrl
  }
}

Was Sie Nutzern anzeigen

• held ist kein Fehler – zeigen Sie eine normale Bestätigung an.
• Validierungsfehler: neben den Feldern anzeigen (issue.param), idealerweise mit eigenem, übersetztem Text anhand von issue.code.
• Alles andere: eine allgemeine Meldung. Zeigen Sie message Endnutzern nicht wörtlich an – der Text ist für Entwickler geschrieben.
• Protokollieren Sie code, status und gegebenenfalls die Nachrichten-ID – damit lassen sich Supportanfragen schnell klären.

Die Helfer für React, React Native, Vue und Svelte werfen aus send() nie eine Ausnahme; sie legen den Fehler stattdessen in ihrem error-State ab.