Good error design is clear, useful, and friendly. Designing concise and accurate error messages unblocks users and builds trust by meeting people where they are.
Keep it simple. Regardless of the design component or message length, the most comprehensive error messages include:
- What happened - event
- Why it happened - explanation
- What to do next - solution
- More information - major bonus points if we can link to relevant information and resources
The event that caused the error or, if unknown, an accurate depiction of what occured. Be sure to communicate the general outcome of the error. Use plain language and focus on what it means to the user.
Killing sandbox due to timeout1 $timeoutms`;
Your build didn’t connect to the Vercel API and timed out after 45 minutes. Redeploy to try again.
Why did it happen?
Be honest and neutral. Did a third-party app fail? You can say that. Avoid blame but don’t be inauthentic by creating any layers of ambiguity. Tell the truth and be nice, but don’t exaggerate or overpromise.
You don’t have permission to access this resource.
The session token expired or invalidated. Tokens are available for a limited amount of time. Refresh to renew your token and try again.
What do I do next?
Tell people what they can do about it. If there’s nothing for them to do, then explain what the product is doing. This should be as simple and actionable as possible. Linking to a helpful article + additional resources can be useful, but only if that article is specific enough for the use case.
An unexpected error occured. Our team has already been notified and are working to resolve the issue, please try again shortly.
An unexpected error occured and the build process could not complete. Try redeploying. If the problem continues, contact Vercel Support→
Ensure your custom label includes the word "error".