I happened upon an error once
And it was drab and dire!
Instead of bringing sadness
What if errors could inspire?

Off to vim, I rushed to write
The PR was merged in no time.
Now every time you get a warning
It’s paired with a cute rhyme!

We completely redid our error messages, adding more than just a bit of whimsy. But first, a sample of some of the poems!

Want to see more? Here's a complete list.

Errors are a huge aspect of programming. If everything just worked like we expected it to work, being a programmer would be the easiest job in the world. Alas, a huge part of what goes into a programming job is figuring out why something that should be working mysteriously isn’t. Basically, developers spend a lot of time deciphering error messages!

Our error messages were in need of a little bit of love, so we got to work and redid them!

Originally, here’s what they looked like:

{"error": "Not Found", "description": "Version not found", "errors": null }

And now, they same error looks like this:

{
  "error": "VERSION_FORK_NOT_FOUND",
  "message": "We couldn't find the version (1.0.2) you're trying to fork from",
  "suggestion": "You need to pass an existing version (1.0.0, 1.0.1) in via the `for` parameter",
  "docs": "https://developer.example.com/logs/1a70daae-c1a7-11ea-b3de-0242ac130004",
  "help": "If you need help, email support@readme.io and mention log '1a70daae-c1a7-11ea-b3de-0242ac130004'.",
  "poem": [
    "This request unfortunately failed",
    "But hey, I guess that's life",
    "We couldn't find your version fork",
    "Or your version spoon or version knife"
  ]
}

Wayyyyy more useful information in there now, right? Let’s walk through it line-by-line!

error: A unique ID for every error message

We used to just send out http status codes, like Not Found or Bad Request as our identifier. That makes it hard to handle specific errors in the code, so instead we created unique codes for every type of error.

We want people to check for these, rather than trying to programmatically figure out what to do based on a longer error message. These are meant to be referenced by the code, so these won’t ever change.

message: Descriptive message of what went wrong

We already sent a message before, but now each one is rewritten tailored to the user. We tried to be as verbose as possible in diagnosing the error, so that the person reading the message knew exactly what was going on.

One of the biggest changes was adding variables! Rather than just saying something like “the version you specified...”, we do our best to do things like show them what we’re seeing (such as "the version you specified (v1.0)..."). Here's some examples:

• When we say your API key isn’t right, we show you a few characters of what you sent us to help with debugging
• If you don’t have permission to do something, we tell you who does
• When you pick a value that doesn’t exist, we list the available things that do exist ("...you need to pick an existing version (1.0, 1.1, 1.2)...")

suggestion: How to fix it

Most of the time, error messages focus on the problem and leaves it at that. How negative!

They dutifully report what went wrong, which makes sense… but they usually stop just short of telling us what we actually want to know, which is how to fix the problem. That’s a job for Stack Overflow or something, I suppose.

We added a required suggestion field for every error message. While the message field answers “what’s wrong”, the suggestion answers “how to fix it”. We don’t want our users to have to do much detective work when they hit an error. We also do our best to be specific, like linking directly to the correct docs page or telling them what to change.

docs: A link to more information

We have a new feature, API Metrics, and wanted to show it off! Not only can you see information about the endpoint you called... you can see the actual log of the call you made! This way, you can see exactly what we see, see the endpoints' documentation, get details about the error, share it with our support, rerun the request, and more.

If you like this feature, contact us or try it on your ReadMe project! We’re always excited to help people get started with putting realtime logs in their docs.

help: How to contact us

We include our email address and a way to reference the log so we can look it up. On our end, when someone emails us the code, we can search for it (again, using API Metrics!) and see exactly what they sent and what we returned. No need for a “hmm well it’s working for us” or "can you show us what you saw" back-and-forth!

poem: Err on the side of whimsy

And finally, the poem! One of our core values at ReadMe is to err on the side of whimsy, and what better place to live up to it than in an error? So we wrote a unique poem for each error message:

Want to see more? Here's a complete list.

That's a wrap!

To recap, here's what every single error message from ReadMe now contains:

• error: Unique IDs for every error message
• message: Descriptive messages of what went wrong
• suggestion: How to fix the issue
• docs: Link to more information
• help: How to contact us
• poem: Our company-mandated dose of whimsy!

Hopefully you never see a ReadMe API error out in the wild! But if you do, our goal is to make it as easy (and fun) as possible to vanquish!