Error Handling Checklist | Development Standards

Demo 1 — Field-Level Error

Click “Trigger Field Error” to show an inline field error beneath the input. Click “Clear Error” or start typing to dismiss it.

Email Field with Inline Error

Email Address *

Shown directly below the field they apply to
Specific and human-readable — not just “Invalid”
Error clears when the user starts correcting the field
Scroll to the first error on submit when needed

Demo 2 — Form Banner Error

Click “Trigger API Error” to show a persistent red banner at the top of the form. Dismiss it with the × button.

Mini Form with API Error Banner

Unable to save changes.

You do not have permission to edit this project.

Name

Email

Form does not reset after a failed API call
Field-specific API errors map back to the correct field
General API errors appear in a banner above the submit button
Submit button loading state is removed after error

Demo 3 — Page-Level Error

Toggle between normal data view and error states. Retry simulates recovering from the error after 1.2 seconds.

Page State Switcher

Projects loaded successfully

Showing 12 projects across 3 teams.

Alpha Project Active

Beta Dashboard Draft

Gamma Campaign Paused

⚠️

Something went wrong.

We couldn't load your projects. This is our fault, not yours.

📡

No internet connection.

Check your connection and try again. Your unsaved data is still here.

Page-level failures show an error state, not a blank page
Retry button is available
Network failure preserves entered form data
Slow connection keeps loading visible until complete or timeout

Error Types & Where They Appear

Error Type	Source	Where to Show
Required field empty	Client validation	Inline below the field
Invalid format	Client validation	Inline below the field
Business rule failure	API response	Inline field or form banner
API server error	API response	Form banner or error toast
Network failure	Browser/fetch	Toast or inline banner
Session expired	API response	Redirect to login with message

API Error Code → User Message Mapping

Map every API error code to a plain-English message before displaying it. Never show raw codes or stack traces.

Error Code	HTTP Status	User-Facing Message
`AUTH_REQUIRED`	401	Please log in to continue.
`FORBIDDEN`	403	You don't have permission to do this.
`NOT_FOUND`	404	This record no longer exists.
`VALIDATION_ERROR`	422	Shows field-level errors inline.
`SERVER_ERROR`	500	Something went wrong. Please try again.
`NETWORK_ERROR`	—	Check your internet connection.

Permission and Auth Errors

403 shows a readable permission message
401 redirects to login with a clear reason
Removed access is handled gracefully instead of leaving stale UI

What Never to Do

Never leave errors only in the console
Never show raw backend codes or stack traces to the user
Never clear the form after a failed submission
Never render a blank page when load fails