Copy page

Developer Guide

Error Handling

Every backend error arrives as an RFC 7807 application/problem+json body (the BE's errorHandler guarantees it — see the BE api-conventions page). src/lib/errors/ is the single path that parses and presents those problems. Components never inspect res.status raw and never string-match error.message.

There is exactly one surfacing API: pushNotification(input) from src/lib/errors/app-errors.ts. No direct toast.* calls for errors, no alternate push helpers.

The pipeline

Code
fetch/api call → non-2xx
  → api.ts               parse problem+json body (handleRFC7807Error / apiFetch)
  → pushNotification(errorData)
      → toast.*            always shown (unless toast:false) — impact → severity style
      → appErrors store    event card added when impact !== NONE
  → ErrorsPanel            shell sheet panel listing appErrors (50-entry ring buffer)
  → RfcErrorDialog         structured inspection of a stored RFC7807 entry

Layer	Owns
rfc7807.ts	wire shape — RFC7807Error, safe parse of problem+json
rfc7807-mapper.ts	problem → domain error mapping (field errors, auth-domain keys)
app-errors.ts	pushNotification + appErrors store + ImpactLevel
http-status.ts	status constants/semantics used by api.ts
toast.ts	the toast primitives pushNotification routes through
ErrorsPanel.svelte	the shell panel rendering appErrors event cards
rfc-error-dialog.svelte	dialog that inspects a stored problem entry

pushNotification contract

• Input is NotificationInput or an RFC7807 object — auto-detected by the presence of type (string) + status (number). RFC7807 input is normalized: severity → impact, title → scope, detail → message, internal_code/status/instance → danger tags.
• Always toasts — unless toast: false (silent panel entry, used by flows that render the error in-place, e.g. login/MFA/change-password).
• Adds an appErrors event card — for every impact except NONE (NONE is success: toast only, no event card).
• Impact → toast style: CRITICAL → toast.critical (urgent red), HIGH → toast.error, MEDIUM → toast.warning, LOW → toast.info, NONE → toast.success.
• i18n — messageKey/scopeKey are translated via t(); literal message/scope are the fallback.
• Returns the error id for programmatic dismissal.

Code
// RFC7807 verbatim — the common case (api.ts does this automatically)
pushNotification(errorData);

// Manual notification with a key + scope
pushNotification({
  impact: 'HIGH',
  messageKey: 'app.errors.saveFailed',
  scopeKey: 'app.scope.customers',
});

// Silent panel entry (no toast) for an in-place error
pushNotification({ ...err, toast: false });

Contract rules

• Parse, don't guess — api.ts already pushes every detected RFC7807 body; callers only push manually when they consumed the body themselves.
• Field errors ride the problem — validation failures carry errors[]; forms display them inline rather than toasting raw detail.
• Unhandled rejections are surfaced too — AppShell listens on unhandledrejection and pushes a HIGH notification, so no async failure is invisible.
• detail is developer-facing — user copy comes from message/ messageKey, optionally translated through t(); never render raw server detail as the primary message.