Canon Error Handling

CANON · Error Handling

Errors are inevitable. Showing them well is the difference between a product that feels reliable and one that feels broken.

Error message anatomy

Every error message answers three questions:

1. What failed? — Name the thing. "Couldn't save your changes."
2. Why? — Give the cause if known. "The server didn't respond."
3. How to fix? — Give the action. "Check your connection and try again."

Bad:  "Error."
Bad:  "Something went wrong."
Good: "Couldn't save your changes — connection lost. Check your network and retry."

Error display patterns

Validation timing

From canon-forms:

• Validate on blur (when user leaves the field), not on every keystroke.
• Show error after first submission attempt, then live-validate on change.
• Never show errors before the user has interacted with the field.

Retry logic

Show the retry state: "Retrying in 3s... [Retry now]"

Optimistic UI rollback

When using optimistic updates (show success instantly, sync in background), the error case is the rollback:

1. Apply the change immediately in the UI.
2. Send the request.
3. On failure: revert the UI, show a toast explaining what happened.
4. "Couldn't delete item — restored. [Try again]"

Error boundaries (React)

class ErrorBoundary extends React.Component {
  state = { hasError: false };
  static getDerivedStateFromError() { return { hasError: true }; }
  componentDidCatch(error, info) { logErrorToService(error, info); }
  render() {
    if (this.state.hasError) {
      return <ErrorFallback => this.setState({ hasError: false })} />;
    }
    return this.props.children;
  }
}

• Wrap at the feature level, not the app level (one broken widget shouldn't blank the page).
• Fallback UI should have a retry action.
• Log the error to your monitoring service.

Offline handling

• Detect via navigator.onLine + online/offline events (unreliable alone; also check fetch failures).
• Show a persistent banner: "You're offline. Changes will sync when you're back."
• Queue offline actions, replay on reconnect.
• Never show "Something went wrong" for offline — name it.

Anti-patterns

Audit checklist

• Every error message says what, why, and how
• Inline errors for fields, banners for pages, toasts for background
• Validation on blur, not on keystroke
• Retry button for recoverable errors
• Auto-retry uses exponential backoff with visible state
• Optimistic UI has a rollback + explanation
• Error boundaries at feature level (React)
• Offline state shows a banner, not a generic error
• No "Oops!", no stack traces, no bare error codes

Sources

• WCAG 2.2 · 3.3.1 Error Identification, 3.3.3 Error Suggestion
• canon-ux-writing for message anatomy
• canon-states for empty/error/loading patterns
• React docs · Error Boundaries