Adding Clarity and a Dash of Whimsy to API Error Messages I happened upon an error onceAnd it was drab and dire!Instead of bringing sadnessWhat if errors could inspire? Off to vim, I rushed to writeThe PR was merged in no time.Now every time you get a warningIt’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 [email protected] 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" ] } Way 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 want to make API debugging as easy as possible, which is why we created metrics and My Developers. With their help, you can not only 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. An example of the error page we link to If you want to try adding metrics to your own docs, 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 Metrics and My Developers) and see exactly what they sent and what we returned. No need for “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!