Humanize error message copy

[redoPop]

In a recent tweet, Brad Frost complained that our 502 error message "isn't good."

This issue is to assess our current error message headlines and other copy, and to suggest replacements where needed.

Here's a list of our current status pages, with headline text and links to markdown sources:

• 401: "Sorry, you are not authorized to see that." (markdown)
• 403: "Sorry, access to that is not allowed." (markdown)
• 404: "Sorry, we can't find what you're looking for." (markdown)
• 405: "Sorry, that request is not supported for this resource." (markdown)
• 410: "Sorry, this content has been permanently removed." (markdown)
• 422: "Sorry, there was an error with your request." (markdown)
• 429: "Sorry, we're getting too many requests right now." (markdown)
• 500: "Sorry, we're experiencing technical difficulties. Please try later." (markdown)
• 501: "Sorry, that method is not yet available." (markdown)
• 502: "Sorry, an upstream server sent an invalid response. Please try later." (markdown)
• 503: "Sorry, the server is temporarily unavailable. Please try later." (markdown)
• 504: "Sorry, an upstream server did not respond in time. Please try later." (markdown)
• 508: "Sorry, time has temporarily become a loop. Please try again and again earlier." (markdown)

In suggesting replacements, please bear in mind that copied or retyped error message headlines are sometimes all that developers receive in error reports. Headline text should therefore be distinct and specific, but ideally not overwhelmingly verbose or technical.

[redoPop]

502, 503 and 504 are probably our priorities here. (501's headline may sound technical, but it's extremely unusual for a non-technical user to encounter that error page.)

Rough translations of those error messages:

• 502: Roadrunner got bad data from one of the external services it talks to. (The term "upstream server" signifies that the issue originates within an external service rather than Roadrunner itself.)
• 503: Roadrunner's own server is unavailable. (The term "the server" signifies that the issue is with Roadrunner's own server rather than anything external.)
• 504: An external service was taking an unusually long time to provide data that Roadrunner needed before it could render the current page. Roadrunner became impatient and gave up.

[mmcwatters]

@redoPop — thanks. I'll chomp away on this over the next few days.

[mmcwatters]

I was thinking of creating unique messages for each error type, and then it occurred to me that most, if not all, people who arrive at such a screen aren't interested in the specific details. If they're that kind of person, well, we provide the error code which they'd likely be familiar with (and we could even link the code to Wikipedia if we choose).

Perhaps the rather generic message we use on 500 is sufficient, especially if we include some kind of notification mechanism.

@redoPop

[redoPop]

I can implement this if the UX of a less specific error message seems strongly preferable, but I'd prefer a different solution. There are a few reasons developers prefer specific error messages:

• Developers need to be able to tell at a glance if an error changes when the page is refreshed – it's always annoying to realize that the 503 you were debugging had become a 502 without you noticing. I know from personal experience that I'm more likely to notice a change in message/headline than a change in numeric HTTP error code even when it's printed on the page.
• Developers sometimes misremember the meaning of numeric HTTP status codes. I know from past experience that I've confused or conflated HTTP status codes. I've never done this when they've been accompanied by printed error messages.
• Copied or retyped message headlines – without the parenthetical HTTP code – are sometimes all that developers/CS receive in error reports. In those circumstances it's very helpful if the message relays identifiable indication of the error.

Our planned solution for #9 should help avoid the third problem. Perhaps the other two problems could be mitigated by adding more specific error text below a generic heading, like:

I'd prefer the heading itself contain the specific messaging, but it's a challenge to produce message summaries that satisfy both user groups.

[mmcwatters]

@redoPop — ah, that makes sense. Thanks for the info.

I like the solution above—I realize it's not optimal for the engineers, but perhaps when they get used to it, they'll be conditioned to looking below the generic copy.

May I suggest that we move the error code down, remove the parents, and place it in front of the specific error, e.g.:

502 An upstream server sent an invalid response.

[redoPop]

I can certainly move the numeric HTTP status code closer to the specific message as you suggest, but removing my parents seems a little extreme at this point.

[mmcwatters]

That was supposed to be pants

[redoPop]

👖 502: An upleg server sent an invalid response.

[mmcwatters]

DYING 😭

[celly]

@alexdean

[mtwentyman]

We did it, ya!

[alexdean]

After he's gone, can we delete all the CSS from everywhere?