fix(audit-tier-2): error-surface hygiene — toastError + CodedError sweep

Two mechanical sweeps closing the audit's HIGH §16 + MED §11 findings:

* 38 client components / 56 toast.error sites converted to
  toastError(err) so the new admin error inspector becomes usable from
  user-reported issues — every failed inline-edit, save, send, archive,
  upload, etc. now carries the request-id + error-code (Copy ID action).
* 26 service files / 62 bare-Error throws converted to CodedError or
  the existing AppError subclasses.  Adds new error codes:
  DOCUMENSO_UPSTREAM_ERROR (502), DOCUMENSO_AUTH_FAILURE (502),
  DOCUMENSO_TIMEOUT (504), OCR_UPSTREAM_ERROR (502),
  IMAP_UPSTREAM_ERROR (502), UMAMI_UPSTREAM_ERROR (502),
  UMAMI_NOT_CONFIGURED (409), and INSERT_RETURNING_EMPTY (500) for
  post-insert returning-empty guards.
* Five vitest assertions updated to match the new user-facing wording
  (client-merge "already been merged", expense/interest "couldn't find
  that …", documenso "signing service didn't respond").

Test status: 1168/1168 vitest, tsc clean.

Refs: docs/audit-comprehensive-2026-05-05.md HIGH §16 (auditor-H Issue 1)
+ MED §11 (auditor-G Issue 1).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/admin/brochures-admin-panel.tsx

@@ -29,6 +29,7 @@ import { Label } from '@/components/ui/label';
 import { Textarea } from '@/components/ui/textarea';
 import { Switch } from '@/components/ui/switch';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface BrochureRow {
   id: string;
@@ -123,8 +124,7 @@ function BrochureCard({ brochure, onChange }: { brochure: BrochureRow; onChange:
       toast.success('Default brochure updated');
       onChange();
     },
-    onError: (e) =>
-      toast.error(e instanceof Error ? e.message : 'Could not update default brochure'),
+    onError: (e) => toastError(e),
   });
 
   const archiveMutation = useMutation({
@@ -133,7 +133,7 @@ function BrochureCard({ brochure, onChange }: { brochure: BrochureRow; onChange:
       toast.success('Brochure archived');
       onChange();
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Archive failed'),
+    onError: (e) => toastError(e),
   });
 
   async function handleUpload(file: File) {
@@ -168,7 +168,7 @@ function BrochureCard({ brochure, onChange }: { brochure: BrochureRow; onChange:
       toast.success('New version uploaded');
       onChange();
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Upload failed');
+      toastError(err);
     } finally {
       setUploading(false);
     }
@@ -287,7 +287,7 @@ function CreateBrochureDialog({
       onCreated();
       onOpenChange(false);
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Could not create brochure'),
+    onError: (e) => toastError(e),
   });
 
   return (

src/components/admin/documenso/documenso-test-button.tsx

@@ -6,6 +6,7 @@ import { toast } from 'sonner';
 
 import { Button } from '@/components/ui/button';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface HealthResponse {
   ok: boolean;
@@ -35,7 +36,7 @@ export function DocumensoTestButton() {
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Test failed';
       setResult({ ok: false, error: message });
-      toast.error(message);
+      toastError(err);
     } finally {
       setPending(false);
     }

src/components/admin/duplicates/duplicates-review-queue.tsx

@@ -10,6 +10,7 @@ import { PageHeader } from '@/components/shared/page-header';
 import { EmptyState } from '@/components/shared/empty-state';
 import { Skeleton } from '@/components/ui/skeleton';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { cn } from '@/lib/utils';
 
 interface CandidatePair {
@@ -104,7 +105,7 @@ function CandidateRow({
       queryClient.invalidateQueries({ queryKey: ['admin', 'duplicates'] });
       queryClient.invalidateQueries({ queryKey: ['clients'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Merge failed'),
+    onError: (err) => toastError(err),
     onSettled: () => setBusy(null),
   });
 
@@ -114,7 +115,7 @@ function CandidateRow({
       toast.message('Dismissed');
       queryClient.invalidateQueries({ queryKey: ['admin', 'duplicates'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Dismiss failed'),
+    onError: (err) => toastError(err),
     onSettled: () => setBusy(null),
   });
 

src/components/admin/forms/form-template-form.tsx

@@ -19,6 +19,7 @@ import {
 } from '@/components/ui/select';
 import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import type { FormField } from '@/lib/validators/form-templates';
 
 interface FormTemplate {
@@ -97,7 +98,7 @@ export function FormTemplateForm({ open, onOpenChange, template, onSaved }: Prop
       onSaved();
       onOpenChange(false);
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Save failed'),
+    onError: (err) => toastError(err),
   });
 
   function updateField(idx: number, patch: Partial<FormField>) {

src/components/admin/forms/form-template-list.tsx

@@ -11,6 +11,7 @@ import { Button } from '@/components/ui/button';
 import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { PageHeader } from '@/components/shared/page-header';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import type { FormField } from '@/lib/validators/form-templates';
 import { FormTemplateForm } from './form-template-form';
 
@@ -41,7 +42,7 @@ export function FormTemplateList() {
       toast.success('Template deleted');
       qc.invalidateQueries({ queryKey: ['admin', 'form-templates'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Delete failed'),
+    onError: (err) => toastError(err),
   });
 
   return (

src/components/admin/invitations/invitations-manager.tsx

@@ -12,6 +12,7 @@ import { Switch } from '@/components/ui/switch';
 import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface Invite {
   id: string;
@@ -56,7 +57,7 @@ export function InvitationsManager() {
       setIsSuperAdmin(false);
       qc.invalidateQueries({ queryKey: ['admin', 'invitations'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to send invite'),
+    onError: (err) => toastError(err),
   });
 
   const resendMutation = useMutation({
@@ -66,7 +67,7 @@ export function InvitationsManager() {
       toast.success('Invite resent');
       qc.invalidateQueries({ queryKey: ['admin', 'invitations'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to resend'),
+    onError: (err) => toastError(err),
   });
 
   const revokeMutation = useMutation({
@@ -75,7 +76,7 @@ export function InvitationsManager() {
       toast.success('Invite revoked');
       qc.invalidateQueries({ queryKey: ['admin', 'invitations'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to revoke'),
+    onError: (err) => toastError(err),
   });
 
   return (

src/components/admin/sales-email-config-card.tsx

@@ -23,6 +23,7 @@ import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface SalesConfigResponse {
   data: {
@@ -160,7 +161,7 @@ export function SalesEmailConfigCard() {
       toast.success('Sales email settings saved');
       await refresh();
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Save failed');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/admin/shared/settings-form-card.tsx

@@ -18,6 +18,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 export type SettingFieldType =
   | 'string'
@@ -116,7 +117,7 @@ export function SettingsFormCard({ title, description, fields, extra }: Settings
       toast.success(`Saved ${changedFields.length} setting(s)`);
       setOriginals(values);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Save failed');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/admin/storage-admin-panel.tsx

@@ -17,6 +17,7 @@ import {
   DialogTitle,
 } from '@/components/ui/dialog';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 type BackendName = 's3' | 'filesystem';
 
@@ -57,8 +58,7 @@ export function StorageAdminPanel() {
       setDryRun(result.data);
       setConfirmOpen(true);
     },
-    onError: (e) =>
-      toast.error(e instanceof Error ? e.message : 'Storage migration dry-run failed'),
+    onError: (e) => toastError(e),
   });
 
   const migrateMutation = useMutation({
@@ -74,7 +74,7 @@ export function StorageAdminPanel() {
       toast.success(`Storage migration complete (${copied} file${copied === 1 ? '' : 's'} copied)`);
       queryClient.invalidateQueries({ queryKey: ['admin', 'storage', 'status'] });
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Storage migration failed'),
+    onError: (e) => toastError(e),
   });
 
   const testMutation = useMutation({

src/components/admin/website-analytics/umami-test-button.tsx

@@ -6,6 +6,7 @@ import { toast } from 'sonner';
 
 import { Button } from '@/components/ui/button';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface TestResponse {
   ok: boolean;
@@ -38,7 +39,7 @@ export function UmamiTestButton() {
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Test failed';
       setResult({ ok: false, error: message });
-      toast.error(message);
+      toastError(err);
     } finally {
       setPending(false);
     }

src/components/berths/berth-detail-header.tsx

@@ -28,6 +28,7 @@ import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { BerthForm } from './berth-form';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { updateBerthStatusSchema, type UpdateBerthStatusInput } from '@/lib/validators/berths';
 import { BERTH_STATUSES } from '@/lib/constants';
 
@@ -123,8 +124,7 @@ function StatusChangeDialog({
       reset();
       onOpenChange(false);
     } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : 'Failed to update status';
-      toast.error(message);
+      toastError(err);
     }
   }
 

src/components/berths/berth-documents-tab.tsx

@@ -23,6 +23,7 @@ import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { toast } from 'sonner';
 
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Badge } from '@/components/ui/badge';
@@ -83,7 +84,7 @@ export function BerthDocumentsTab({ berthId }: { berthId: string }) {
       toast.success('Rolled back to selected version.');
     },
     onError: (err: Error) => {
-      toast.error('Rollback failed', { description: err.message });
+      toastError(err);
     },
   });
 
@@ -141,7 +142,7 @@ export function BerthDocumentsTab({ berthId }: { berthId: string }) {
       toast.success('PDF uploaded.');
     },
     onError: (err: Error) => {
-      toast.error('Upload failed', { description: err.message });
+      toastError(err);
     },
   });
 

src/components/berths/berth-form.tsx

@@ -21,6 +21,7 @@ import { Separator } from '@/components/ui/separator';
 import { Switch } from '@/components/ui/switch';
 import { TagPicker } from '@/components/shared/tag-picker';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { updateBerthSchema, type UpdateBerthInput } from '@/lib/validators/berths';
 import {
   BERTH_AREAS,
@@ -172,8 +173,7 @@ export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
       toast.success('Berth updated');
       onOpenChange(false);
     } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : 'Failed to update berth';
-      toast.error(message);
+      toastError(err);
     }
   }
 

src/components/berths/pdf-reconcile-dialog.tsx

@@ -21,6 +21,7 @@ import { useMutation, useQueryClient } from '@tanstack/react-query';
 import { toast } from 'sonner';
 
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { Button } from '@/components/ui/button';
 import { Checkbox } from '@/components/ui/checkbox';
 import {
@@ -93,7 +94,7 @@ export function PdfReconcileDialog({
       onClose();
     },
     onError: (err: Error) => {
-      toast.error('Apply failed', { description: err.message });
+      toastError(err);
     },
   });
 

src/components/clients/contacts-editor.tsx

@@ -27,6 +27,7 @@ import { InlineEditableField } from '@/components/shared/inline-editable-field';
 import { InlinePhoneField } from '@/components/shared/inline-phone-field';
 import { PhoneInput, type PhoneInputValue } from '@/components/shared/phone-input';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { cn } from '@/lib/utils';
 
 interface Contact {
@@ -161,7 +162,7 @@ function ContactRow({
     try {
       await onUpdate({ isPrimary: !contact.isPrimary });
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to update');
+      toastError(err);
     }
   }
 
@@ -170,7 +171,7 @@ function ContactRow({
     try {
       await onUpdate({ channel: next });
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to update');
+      toastError(err);
     }
   }
 
@@ -343,7 +344,7 @@ function NewContactForm({
           label: label.trim() || undefined,
         });
       } catch (err) {
-        toast.error(err instanceof Error ? err.message : 'Failed to add contact');
+        toastError(err);
       } finally {
         setSaving(false);
       }
@@ -354,7 +355,7 @@ function NewContactForm({
     try {
       await onSave({ channel, value: value.trim(), label: label.trim() || undefined });
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to add contact');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/clients/gdpr-export-button.tsx

@@ -22,6 +22,7 @@ import {
 import { Badge } from '@/components/ui/badge';
 import { usePermissions } from '@/hooks/use-permissions';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface ExportRow {
   id: string;
@@ -79,7 +80,7 @@ export function GdprExportButton({ clientId }: { clientId: string }) {
       setEmailOverride('');
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Failed to queue export');
+      toastError(err);
     },
   });
 
@@ -92,7 +93,7 @@ export function GdprExportButton({ clientId }: { clientId: string }) {
       );
       window.open(res.data.url, '_blank', 'noopener');
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to fetch download URL');
+      toastError(err);
     }
   }
 

src/components/companies/company-detail-header.tsx

@@ -13,6 +13,7 @@ import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { CompanyForm } from '@/components/companies/company-form';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface CompanyDetailHeaderCompany {
   id: string;
@@ -66,7 +67,7 @@ export function CompanyDetailHeader({ company }: CompanyDetailHeaderProps) {
       router.push(`/${portSlug}/companies` as any);
     },
     onError: (err: Error) => {
-      toast.error(err.message || 'Failed to archive company');
+      toastError(err);
     },
   });
 

src/components/companies/company-members-tab.tsx

@@ -25,6 +25,7 @@ import {
 import { EmptyState } from '@/components/shared/empty-state';
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { AddMembershipDialog } from './add-membership-dialog';
 
 interface MembershipRow {
@@ -112,7 +113,7 @@ export function CompanyMembersTab({ companyId, portSlug }: CompanyMembersTabProp
       toast.success('Membership ended');
     },
     onError: (err: Error) => {
-      toast.error(err.message || 'Failed to end membership');
+      toastError(err);
     },
   });
 
@@ -126,7 +127,7 @@ export function CompanyMembersTab({ companyId, portSlug }: CompanyMembersTabProp
       toast.success('Primary contact updated');
     },
     onError: (err: Error) => {
-      toast.error(err.message || 'Failed to set primary');
+      toastError(err);
     },
   });
 

src/components/documents/create-document-wizard.tsx

@@ -18,6 +18,7 @@ import {
 } from '@/components/ui/select';
 import { PageHeader } from '@/components/shared/page-header';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { DOCUMENT_TYPES } from '@/lib/constants';
 
 const SIGNER_ROLES = ['client', 'sales', 'approver', 'developer', 'other'] as const;
@@ -158,7 +159,7 @@ export function CreateDocumentWizard({ portSlug }: CreateDocumentWizardProps) {
       toast.success('Document created');
       router.push(`/${portSlug}/documents/${res.data.id}`);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to create document');
+      toastError(err);
       setSubmitting(false);
     }
   };

src/components/documents/document-detail.tsx

@@ -13,6 +13,7 @@ import { PageHeader } from '@/components/shared/page-header';
 import { StatusPill, type StatusPillStatus } from '@/components/ui/status-pill';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface DetailDoc {
   id: string;
@@ -151,7 +152,7 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
       toast.success('Reminder sent');
       queryClient.invalidateQueries({ queryKey: ['document-detail', documentId] });
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to send reminder');
+      toastError(err);
     }
   };
 
@@ -163,7 +164,7 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
       toast.success('Document cancelled');
       router.push(`/${portSlug}/documents`);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Cancel failed');
+      toastError(err);
       setIsCancelling(false);
     }
   };
@@ -177,7 +178,7 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
         `Email composer prepared for ${draft.data.to.length} signer${draft.data.to.length === 1 ? '' : 's'} - opens in PR8 wizard`,
       );
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to prepare email');
+      toastError(err);
     }
   };
 
@@ -357,9 +358,7 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
                             queryKey: ['document-detail', documentId],
                           });
                         } catch (err) {
-                          toast.error(
-                            err instanceof Error ? err.message : 'Failed to remove watcher',
-                          );
+                          toastError(err);
                         }
                       }}
                       className="text-muted-foreground hover:text-destructive"

src/components/email/compose-dialog.tsx

@@ -23,6 +23,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface Account {
   id: string;
@@ -86,7 +87,7 @@ export function ComposeDialog({
       setSubject('');
       setBody('');
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Send failed'),
+    onError: (err) => toastError(err),
   });
 
   return (

src/components/email/email-accounts-list.tsx

@@ -19,6 +19,7 @@ import {
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/components/ui/sheet';
 import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface Account {
   id: string;
@@ -73,7 +74,7 @@ export function EmailAccountsList() {
       setSheetOpen(false);
       qc.invalidateQueries({ queryKey: ['email', 'accounts'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to connect account'),
+    onError: (err) => toastError(err),
   });
 
   const toggleMutation = useMutation({

src/components/expenses/expense-detail.tsx

@@ -12,6 +12,7 @@ import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { toast } from 'sonner';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 import type { ExpenseRow } from './expense-columns';
 import { ExpenseDuplicateBanner } from './expense-duplicate-banner';
@@ -122,7 +123,7 @@ export function ExpenseDetail({ expenseId, onEdit, onArchived }: ExpenseDetailPr
       onArchived?.();
     },
     onError: (e) => {
-      toast.error(e instanceof Error ? e.message : 'Archive failed');
+      toastError(e);
       setArchiveOpen(false);
     },
   });

src/components/interests/inline-stage-picker.tsx

@@ -8,6 +8,7 @@ import { toast } from 'sonner';
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import { Textarea } from '@/components/ui/textarea';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { cn } from '@/lib/utils';
 import {
   PIPELINE_STAGES,
@@ -65,7 +66,7 @@ export function InlineStagePicker({
     },
     onError: (err) => {
       setPendingStage(null);
-      toast.error(err instanceof Error ? err.message : 'Failed to change stage');
+      toastError(err);
     },
   });
 

src/components/invoices/invoice-detail.tsx

@@ -25,6 +25,7 @@ import {
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { InvoicePdfPreview } from './invoice-pdf-preview';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 import { recordPaymentSchema, type RecordPaymentInput } from '@/lib/validators/invoices';
 
@@ -99,7 +100,7 @@ export function InvoiceDetail({ invoiceId }: InvoiceDetailProps) {
       queryClient.invalidateQueries({ queryKey: ['invoices', invoiceId] });
       queryClient.invalidateQueries({ queryKey: ['invoices'] });
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Could not send invoice'),
+    onError: (e) => toastError(e),
   });
 
   const paymentForm = useForm<RecordPaymentInput>({
@@ -118,7 +119,7 @@ export function InvoiceDetail({ invoiceId }: InvoiceDetailProps) {
       queryClient.invalidateQueries({ queryKey: ['invoices', invoiceId] });
       queryClient.invalidateQueries({ queryKey: ['invoices'] });
     },
-    onError: (e) => toast.error(e instanceof Error ? e.message : 'Could not record payment'),
+    onError: (e) => toastError(e),
   });
 
   if (isLoading) {

src/components/notifications/notification-preferences-form.tsx

@@ -7,6 +7,7 @@ import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
 import { Switch } from '@/components/ui/switch';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface Pref {
   notificationType: string;
@@ -72,7 +73,7 @@ export function NotificationPreferencesForm() {
       toast.success('Preferences saved');
       qc.invalidateQueries({ queryKey: ['notifications', 'preferences'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Save failed'),
+    onError: (err) => toastError(err),
   });
 
   function update(type: string, field: 'inApp' | 'email', value: boolean) {

src/components/notifications/reminder-digest-form.tsx

@@ -17,6 +17,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface ReminderPrefs {
   delivery: 'immediate' | 'daily' | 'weekly' | 'off';
@@ -81,7 +82,7 @@ export function ReminderDigestForm() {
       toast.success('Reminder preferences saved');
       qc.invalidateQueries({ queryKey: ['user', 'preferences'] });
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Save failed'),
+    onError: (err) => toastError(err),
   });
 
   if (isLoading) {

src/components/reservations/reservation-detail.tsx

@@ -22,6 +22,7 @@ import { StatusPill, type StatusPillStatus } from '@/components/ui/status-pill';
 import { EmptyState } from '@/components/ui/empty-state';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { ClientLink, YachtLink, BerthLink } from '@/components/reservations/reservation-list';
 
 interface ReservationDoc {
@@ -80,7 +81,7 @@ function EndReservationDialog({ reservationId, open, onOpenChange }: EndReservat
       toast.success('Reservation ended');
       onOpenChange(false);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to end reservation');
+      toastError(err);
     } finally {
       setSubmitting(false);
     }
@@ -245,7 +246,7 @@ export function ReservationDetail({ reservationId, portSlug }: ReservationDetail
                   });
                   toast.success('Reminder sent');
                 } catch (err) {
-                  toast.error(err instanceof Error ? err.message : 'Failed');
+                  toastError(err);
                 }
               }}
             >

src/components/residential/residential-client-detail.tsx

@@ -18,6 +18,7 @@ import { InlinePhoneField } from '@/components/shared/inline-phone-field';
 import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import type { CountryCode } from '@/lib/i18n/countries';
 
 interface ResidentialInterestSummary {
@@ -312,7 +313,7 @@ function NewInterestSheet({
       setNotes('');
       toast.success('Interest added');
     },
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to add'),
+    onError: (err) => toastError(err),
   });
 
   return (

src/components/residential/residential-clients-list.tsx

@@ -18,6 +18,7 @@ import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
 import { PhoneInput, type PhoneInputValue } from '@/components/shared/phone-input';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { cn } from '@/lib/utils';
 import type { CountryCode } from '@/lib/i18n/countries';
 
@@ -246,7 +247,7 @@ function NewResidentialClientSheet({
       toast.success('Residential client added');
     },
     onError: (err) => {
-      toast.error(err instanceof Error ? err.message : 'Failed to create');
+      toastError(err);
     },
   });
 

src/components/shared/addresses-editor.tsx

@@ -11,6 +11,7 @@ import { CountryCombobox } from '@/components/shared/country-combobox';
 import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
 import { InlineEditableField } from '@/components/shared/inline-editable-field';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import type { CountryCode } from '@/lib/i18n/countries';
 import { getCountryName } from '@/lib/i18n/countries';
 import { getSubdivisionName } from '@/lib/i18n/subdivisions';
@@ -119,7 +120,7 @@ function AddressCard({
     try {
       await onUpdate({ isPrimary: true });
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to update');
+      toastError(err);
     }
   }
 
@@ -362,7 +363,7 @@ function NewAddressForm({
         isPrimary: makePrimary,
       });
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to add address');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/shared/inline-country-field.tsx

@@ -2,9 +2,9 @@
 
 import { useRef, useState } from 'react';
 import { Loader2, Pencil } from 'lucide-react';
-import { toast } from 'sonner';
 
 import { CountryCombobox } from '@/components/shared/country-combobox';
+import { toastError } from '@/lib/api/toast-error';
 import { getCountryName, type CountryCode } from '@/lib/i18n/countries';
 import { cn } from '@/lib/utils';
 
@@ -46,7 +46,7 @@ export function InlineCountryField({
       await onSave(next);
       setEditing(false);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to save');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/shared/inline-editable-field.tsx

@@ -2,8 +2,8 @@
 
 import { useEffect, useRef, useState } from 'react';
 import { Loader2, Pencil } from 'lucide-react';
-import { toast } from 'sonner';
 
+import { toastError } from '@/lib/api/toast-error';
 import { Input } from '@/components/ui/input';
 import { Textarea } from '@/components/ui/textarea';
 import {
@@ -85,7 +85,7 @@ export function InlineEditableField(props: InlineEditableFieldProps) {
       await onSave(trimmed === '' ? null : trimmed);
       setEditing(false);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to save');
+      toastError(err);
       setDraft(value ?? '');
     } finally {
       setSaving(false);

src/components/shared/inline-phone-field.tsx

@@ -2,9 +2,9 @@
 
 import { useState } from 'react';
 import { Loader2, Pencil } from 'lucide-react';
-import { toast } from 'sonner';
 
 import { PhoneInput, type PhoneInputValue } from '@/components/shared/phone-input';
+import { toastError } from '@/lib/api/toast-error';
 import { parsePhone } from '@/lib/i18n/phone';
 import type { CountryCode } from '@/lib/i18n/countries';
 import { cn } from '@/lib/utils';
@@ -66,7 +66,7 @@ export function InlinePhoneField({
       await onSave(next);
       setEditing(false);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to save');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/shared/inline-tag-editor.tsx

@@ -3,11 +3,11 @@
 import { useState } from 'react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { Plus, X, Check } from 'lucide-react';
-import { toast } from 'sonner';
 
 import { Button } from '@/components/ui/button';
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { cn } from '@/lib/utils';
 
 interface Tag {
@@ -45,7 +45,7 @@ export function InlineTagEditor({
   const setTags = useMutation({
     mutationFn: (tagIds: string[]) => apiFetch(endpoint, { method: 'PUT', body: { tagIds } }),
     onSuccess: () => qc.invalidateQueries({ queryKey: invalidateKey }),
-    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to update tags'),
+    onError: (err) => toastError(err),
   });
 
   function toggleTag(tagId: string) {

src/components/shared/inline-timezone-field.tsx

@@ -2,9 +2,9 @@
 
 import { useRef, useState } from 'react';
 import { Loader2, Pencil } from 'lucide-react';
-import { toast } from 'sonner';
 
 import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
+import { toastError } from '@/lib/api/toast-error';
 import { formatTimezoneLabel } from '@/lib/i18n/timezones';
 import type { CountryCode } from '@/lib/i18n/countries';
 import { cn } from '@/lib/utils';
@@ -46,7 +46,7 @@ export function InlineTimezoneField({
       await onSave(next);
       setEditing(false);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to save');
+      toastError(err);
     } finally {
       setSaving(false);
     }

src/components/shared/send-document-dialog.tsx

@@ -33,6 +33,7 @@ import { Label } from '@/components/ui/label';
 import { Textarea } from '@/components/ui/textarea';
 import { Input } from '@/components/ui/input';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 const BODY_MAX = 50_000;
 
@@ -149,7 +150,7 @@ export function SendDocumentDialog({
       }
     },
     onError: (err) => {
-      toast.error(err instanceof Error ? err.message : 'Send failed');
+      toastError(err);
     },
   });
 

src/components/yachts/yacht-detail-header.tsx

@@ -15,6 +15,7 @@ import { PermissionGate } from '@/components/shared/permission-gate';
 import { YachtForm } from '@/components/yachts/yacht-form';
 import { YachtTransferDialog } from '@/components/yachts/yacht-transfer-dialog';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface YachtDetailHeaderYacht {
   id: string;
@@ -131,7 +132,7 @@ export function YachtDetailHeader({ yacht }: YachtDetailHeaderProps) {
       router.push(`/${portSlug}/yachts` as any);
     },
     onError: (err: Error) => {
-      toast.error(err.message || 'Failed to archive yacht');
+      toastError(err);
     },
   });