Error feedback

A failed backend call reaches the user through useApiErrorPresenter, as a toast or as an inline alert. This page covers both, and the check that keeps a module's catch blocks on them.

Show a failed call, useApiErrorPresenter

Call useApiErrorPresenter() during setup. Its methods stay callable after an await.

const { presentError, resolveError } = useApiErrorPresenter();

try {
  await $authFetch("/api/report/regenerate", { method: "POST" });
} catch (error) {
  presentError(error, { fallbackKey: "reports.regenerate_failed" });
}

presentError(error, { fallbackKey }) shows the error toast for a failed backend call. The server can answer { message: "error.key", severity: "warning" }. A loaded translation of message wins over fallbackKey. If neither key has a translation, the toast shows core's error.500.description. Unknown text, stack traces and serialized HTTPResult envelopes never reach the screen. A plain translation key as the body still works.

severity is info, warning or error. Without a valid one, an HTTP 4xx answer shows a warning, and an HTTP 5xx answer, a network failure or a timeout shows an error. An AbortError without a failed response shows nothing.

presentError shows at most one toast per failed response in the app, also when another error wraps it in cause. Two different failed responses show two toasts. replaceToastId turns a progress toast into the failure. actions takes { labelKey, onSelect } entries.

resolveError(error, { fallbackKey, params? }) returns { message, severity } for an inline alert, or null for a cancelled call. It never shows a toast and never claims the response, so the same error can resolve inline before or after its toast. The field and confirmation helpers keep their placement and retry behaviour.

ConfirmActionError takes { fallbackKey, params? } and optional ErrorOptions with a cause. It no longer takes translated titles and descriptions. A translated server reason in cause still wins.

Check a module's catch blocks

A module can call assertApiErrorPresentation(["app"]) from @antelopejs/dms/checks/api-error-presentation in its lint script. The check resolves typescript and vue/compiler-sfc from the frontend it checks, so declare both as development dependencies of that frontend.

The check reads the syntax tree. It covers catch blocks, .catch callbacks, .then rejection callbacks, local aliases of the toast, and progress toasts updated on a failure. It does not follow helpers in other files, computed property access, reassignment or shadowed bindings, so review those by hand. It does not prove what every error path of the program shows.

A success toast is plain Nuxt UI: useToast().add({ title: "Saved" }). The DMS toaster keeps clear of a save bar at the bottom of the screen, so the stack rises above it while the bar shows.