--- title: "Error Message UX Best Practices | Utkarsh Panwar" description: "Error message UX best practices: one four-part structure for every error, where it sits, what the retry does, and before-and-after rewrites you can copy." url: https://www.utkarshdesign.com/guides/error-message-design author: Utkarsh Dhairya Panwar updated: 2026-10-08 --- # Error message UX best practices, with rewrites Guide · 6 min read · By [Utkarsh Dhairya Panwar](https://www.utkarshdesign.com/about) · Updated 8 Oct 2026 **A good error message says what happened, what it means for the user (did they lose anything?) and the one action that fixes it, right next to the thing that failed. Use the same structure for every error so people learn it once.** ## Most error advice stops at tone Most advice on error messages is about voice: sound human, don't blame the user, maybe add a joke. That's the smallest part of the problem. The errors that lose users are the friendly ones that still leave the person not knowing what to do. I learned this at FamPay (YC S19), redesigning the timeout, bank-decline and retry states in its iOS app (my payment failure guide covers that work and its results). This page is about the pattern underneath, which works for any error. ## One structure for every error 1. **What happened**: Use the user's terms instead of the system's: "The bank didn't approve this payment" instead of "Transaction failed (code 51)". 2. **What it means for them**: Answer the thing they're worried about, whether that's money leaving their account, a file not saving or a draft going missing. 3. **The one next action**: A button that does the fix, labelled with what it does: "Try again", "Use another card", "Ask your admin". Give one primary action and a secondary at most. 4. **Where to get more**: Optional: a reference code for support or a help link, kept small and placed last. One structure matters more than any single message. When every error has the same shape and sits in the same place, people stop reading the frame and read the content. When errors look different in every corner, nobody builds a habit for recovering and people repeat whatever they did last time. So after you ship a shared pattern, watch repeated mistakes. ## Rewrites | Situation | Before | After | | --- | --- | --- | | Payment timeout | "Something went wrong. Please try again." | "We haven't heard back from your bank yet. Don't pay again: we'll update this screen within a few minutes. [Check status]" | | Bank decline | "Payment failed." | "Your bank declined this payment. Nothing was deducted. [Use another method] [Try again]" | | Form validation | "Invalid input." | "Enter a 10-digit mobile number, without +91." | | No permission | "403 Forbidden" | "Only an org admin can connect this repository. [Ask your admin] or [Copy invite link]" | | Server error (500) | "Internal server error." | "Something broke on our side. Your changes are saved as a draft. [Retry]" | | Page not found (404) | "Oops, looks like you're lost." | "This page was moved or deleted. [Search docs] [Go to dashboard]" | I wrote these for this page to show the pattern; they aren't copied from FamPay's or CodeAnt's screens. Each "after" answers the user's real worry (was I charged twice? did I lose my work?) before offering a button. The timeout version also tells people not to pay again, because an instant retry on an unknown outcome is how double charges happen. ## Turn dead ends into requests Sometimes nothing has failed and the user just isn't allowed to do the thing. At CodeAnt AI, the developer who wanted to connect a repo often lacked the org admin rights to install the GitHub app, and that used to be a dead end. I turned it into a request: email the admin from inside the product, or copy an invite link into team chat. What that did to activation is in how we doubled trial-to-paid. ![CodeAnt Request Admin Approval modal with an invite-link field and Copy button, an org admin email field with a Send button, and a Book a Call link](https://www.utkarshdesign.com/images/codeant-request-admin-approval.webp) _A permission error rewritten as a way to reach the person who can fix it._ Whenever the true message is "someone else has to do this", the best next action is a pre-filled way to reach that person. ## Placement and timing - Show it inline, next to the field or item, for anything the user can fix right there. Toasts disappear before people read them. - Use a full state (screen or sheet) only when the whole task failed, like a payment. - Validate a field when the user leaves it instead of on every keystroke. Being told an email is invalid after typing one letter is just noise. - Keep what the user typed. An error that clears the form is a second error. - Put retry where the original button was, so the thumb or cursor is already there. Preventing an error beats any message about it. At FamPay, users lost the leftover value on one-time vouchers and only found out afterwards, so the fix was a rule shown before purchase instead of a better apology after. I count that as error design done one screen earlier. My guide to reducing support tickets with UX has the full story. ## A quick audit for your product 1. **Collect every error string**: Ask engineering to export the full list. Most teams are surprised by how long it is. 2. **Sort by how often each is shown**: Fix the top ten first. A rare error with bad copy matters less than a common one with average copy. 3. **Check each against the four parts**: What happened, what it means, the next action, more help. Mark which part is missing. 4. **Stage the failures in testing**: Build the failure states into the prototype and give people tasks that hit them. A happy-path review won't find retry gaps. For product copy beyond errors, see UX writing and microcopy for SaaS. If errors are where your users drop off, a UX audit is a quick way to find which ones. [FamPay case study](https://www.utkarshdesign.com/work/fampay): The payment error states and the Cashback Store voucher flow, from finding to shipped screens. ## Questions people ask ### What should an error message include? What happened in plain words, what it means for the user, one clear next action, and optionally a reference code or help link. ### Should error messages use humour? Rarely. A joke on a 404 page is harmless, but a joke when someone's payment failed reads as not taking their money seriously. ### Should error messages show error codes? Only as a small reference for support, placed after the plain explanation. A code on its own tells the user nothing they can act on. ### Toast, inline or full screen? Inline for anything the user can fix in place, a full screen or sheet when the whole task failed. Avoid toasts for errors people need to act on, because they disappear. ## Sources 1. [Error-Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/), Nielsen Norman Group 2. [Usability Testing of Inline Form Validation](https://baymard.com/research-articles/inline-form-validation), Baymard Institute 3. [Understanding Success Criterion 3.3.3: Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html), W3C Web Accessibility Initiative ## Working on this? Tell me what you're building and where it's stuck: [book a 30-minute call](https://cal.com/utkarsh-design/30min), email [work@utkarshdesign.com](mailto:work@utkarshdesign.com) or [send a brief](https://www.utkarshdesign.com/contact). ## Related - [Payment failure UX for timeouts, declines and retries](https://www.utkarshdesign.com/guides/payment-failure-ux) - [UX writing and microcopy for SaaS](https://www.utkarshdesign.com/guides/ux-writing-saas) - [How to reduce support tickets with UX](https://www.utkarshdesign.com/guides/reduce-support-tickets-with-ux) - [UX audit services for SaaS and app products](https://www.utkarshdesign.com/services/ux-audit) --- Utkarsh Dhairya Panwar, Founding Product Designer and Design Engineer (IIT Roorkee; Founding Designer at CodeAnt AI, YC W24). Email: work@utkarshdesign.com · Book a call: https://cal.com/utkarsh-design/30min · Hire: https://www.utkarshdesign.com/hire · About: https://www.utkarshdesign.com/llms.txt