Error handling

Every error from a Frontmail SDK is an instance of FrontmailError (or a subclass) with:

Property	Meaning
code	Stable identifier, e.g. invalid_template_params – see Error codes
status	HTTP status, or 0 for client-side errors
message	English, developer-oriented description
docsUrl	Link to the explanation of this code
details	Extra data – for invalid_template_params the list of issues
retryAfter	Seconds, for rate-limit errors

Subclasses

Class	When
ValidationError	400 / 422 – invalid body or params (details.issues)
AuthError	401, and 403 for forbidden, origin_not_allowed, private_key_required
InsufficientCreditsError	402 – only in reject mode
RateLimitError	429 after retries were exhausted
BlockedError	Blocked in the browser by blockHeadless, blockList or limitRate
NetworkError	No HTTP response: offline, DNS, CORS, timeout (after retries)
FrontmailError	Everything else (e.g. captcha_failed, recipient_suppressed, 5xx)

Example

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

try {
  const { status } = await send('svc_01J9…', 'tpl_contact', params);
  showSuccess(status === 'held' ? 'Received – we will deliver it shortly.' : 'Thank you!');
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.details?.issues ?? []) showFieldError(issue.param, issue.message);
  } else if (err instanceof NetworkError) {
    showError('You seem to be offline. Please try again.');
  } else if (err instanceof BlockedError) {
    showError('Please wait a moment before sending again.');
  } else if (err instanceof FrontmailError && err.code === 'captcha_failed') {
    resetTurnstile();
    showError('Please confirm you are not a robot.');
  } else {
    showError('Sorry, the message could not be sent.');
    console.error(err); // includes code and docsUrl
  }
}

What to show users

• held is not an error – show a normal confirmation.
• Validation issues: show them next to the fields (issue.param), ideally with your own translated text keyed by issue.code.
• Everything else: a generic message. Don’t show message verbatim to end users – it is written for developers.
• Log code, status and the message ID if any – they make support requests fast.

React, React Native, Vue and Svelte helpers never throw from send(); they put the error into their error state instead.