Errors get codes and links
Every error gets a unique code, a link, and more than red to say so.
Guillermo Rauch@rauchg✓ Errors must have globally unique codes & hyperlinks ✓ Red is not enough to signal "error" (8% of men have red-green color blindness)
Guillermo Rauch@rauchg✓ Sweat every word of product copy you render
The codes in the demos are made up; “Learn more” opens Vercel's real error list.
1 · A deploy fails
Deploy in both panes, then view them as 1 in 12 men do.
Red and a shrugBad
Code, link and iconGood
View as
function ErrorCard({ code, title, next }: AppError) {
return (
<div role="alert" className="error">
<TriangleAlert aria-hidden />
<p><strong>{title}</strong> {next}</p>
<code>{code}</code> <CopyButton value={code} />
<a href={`/docs/errors/${code}`}>Learn more</a>
</div>
);
}2 · Support searches the code
Pick a failure, then look up what each user would paste.
Generic copyBad
Unique codeGood
Why it matters, pros and cons
Why it matters
A code turns a vague complaint into one exact page. The words say what happened and what to do; the icon and label carry it without color.
Pros
- Users search the code and fix it themselves.
- Support and logs agree on one string; no screenshots needed.
- Icon plus label reads for color-blind users and in grayscale.
Cons
- Codes are forever: once shipped, never rename or reuse one.
- A doc page per code needs an owner, or the link rots.
- Never put secrets or internal paths in user-facing errors.