Zpracování chyb

Každá chyba z Frontmail SDK je instancí FrontmailError (nebo její podtřídy) a má:

Vlastnost	Význam
code	Stabilní identifikátor, např. invalid_template_params – viz Chybové kódy
status	HTTP status, nebo 0 u chyb na straně klienta
message	Anglický popis určený vývojářům
docsUrl	Odkaz na vysvětlení daného kódu
details	Doplňující data – u invalid_template_params seznam issues
retryAfter	Počet sekund u chyb rate limitu

Podtřídy

Třída	Kdy
ValidationError	400 / 422 – neplatné tělo nebo parametry (details.issues)
AuthError	401 a 403 pro forbidden, origin_not_allowed, private_key_required
InsufficientCreditsError	402 – jen v režimu reject
RateLimitError	429 po vyčerpání všech retry
BlockedError	Zablokováno v prohlížeči pomocí blockHeadless, blockList nebo limitRate
NetworkError	Žádná HTTP odpověď: offline, DNS, CORS, timeout (po všech retry)
FrontmailError	Všechno ostatní (např. captcha_failed, recipient_suppressed, 5xx)

Příklad

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

try {
  const { status } = await send('svc_01J9…', 'tpl_contact', params);
  showSuccess(status === 'held' ? 'Přijato – brzy ji doručíme.' : 'Děkujeme!');
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.details?.issues ?? []) showFieldError(issue.param, issue.message);
  } else if (err instanceof NetworkError) {
    showError('Zdá se, že jste offline. Zkuste to prosím znovu.');
  } else if (err instanceof BlockedError) {
    showError('Před dalším odesláním chvíli počkejte.');
  } else if (err instanceof FrontmailError && err.code === 'captcha_failed') {
    resetTurnstile();
    showError('Potvrďte prosím, že nejste robot.');
  } else {
    showError('Omlouváme se, zprávu se nepodařilo odeslat.');
    console.error(err); // obsahuje code a docsUrl
  }
}

Co ukázat uživatelům

• held není chyba – zobrazte běžné potvrzení.
• Chyby validace: ukažte je u příslušných polí (issue.param), ideálně s vlastním přeloženým textem podle issue.code.
• Všechno ostatní: obecná hláška. message koncovým uživatelům neukazujte doslova – je psaná pro vývojáře.
• Logujte code, status a případně ID zprávy – výrazně urychlí řešení s podporou.

Helpery pro React, React Native, Vue a Svelte z send() nikdy nevyhazují chybu; místo toho ji uloží do svého stavu error.