Obsługa błędów

Każdy błąd z SDK Frontmail jest instancją FrontmailError (lub jej podklasy) i ma:

Właściwość	Znaczenie
code	Stały identyfikator, np. invalid_template_params – zobacz Kody błędów
status	Status HTTP albo 0 dla błędów po stronie klienta
message	Opis po angielsku, przeznaczony dla programistów
docsUrl	Link do wyjaśnienia tego kodu
details	Dodatkowe dane – dla invalid_template_params lista issues
retryAfter	Liczba sekund, dla błędów rate limitu

Podklasy

Klasa	Kiedy
ValidationError	400 / 422 – nieprawidłowa treść żądania lub parametry (details.issues)
AuthError	401 oraz 403 dla forbidden, origin_not_allowed, private_key_required
InsufficientCreditsError	402 – tylko w trybie reject
RateLimitError	429 po wyczerpaniu ponownych prób
BlockedError	Zablokowane w przeglądarce przez blockHeadless, blockList lub limitRate
NetworkError	Brak odpowiedzi HTTP: offline, DNS, CORS, timeout (po wszystkich ponownych próbach)
FrontmailError	Wszystko inne (np. captcha_failed, recipient_suppressed, 5xx)

Przykład

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

try {
  const { status } = await send('svc_01J9…', 'tpl_contact', params);
  showSuccess(status === 'held' ? 'Otrzymaliśmy – wkrótce ją dostarczymy.' : 'Dziękujemy!');
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.details?.issues ?? []) showFieldError(issue.param, issue.message);
  } else if (err instanceof NetworkError) {
    showError('Wygląda na to, że jesteś offline. Spróbuj ponownie.');
  } else if (err instanceof BlockedError) {
    showError('Odczekaj chwilę przed ponownym wysłaniem.');
  } else if (err instanceof FrontmailError && err.code === 'captcha_failed') {
    resetTurnstile();
    showError('Potwierdź, że nie jesteś robotem.');
  } else {
    showError('Przepraszamy, nie udało się wysłać wiadomości.');
    console.error(err); // zawiera code i docsUrl
  }
}

Co pokazać użytkownikom

• held to nie błąd – pokaż zwykłe potwierdzenie.
• Błędy walidacji: pokaż je przy odpowiednich polach (issue.param), najlepiej z własnym przetłumaczonym tekstem dobranym według issue.code.
• Wszystko inne: ogólny komunikat. Nie pokazuj użytkownikom końcowym message dosłownie – jest pisany dla programistów.
• Loguj code, status i ewentualnie ID wiadomości – bardzo przyspieszają kontakt z supportem.

Helpery dla React, React Native, Vue i Svelte nigdy nie rzucają błędów z send(); zamiast tego zapisują błąd w swoim stanie error.