![\"Gif](\"https:\/\/blog.readme.com\/content\/images\/2021\/06\/fine.gif\")
<\/figure>\n\n\n\nWhat a good API error response looks like<\/h1>\n\n\n\n
Error messages from APIs tend to look a bit like this:<\/p>\n\n\n\n
{\"error\": \"Not Found\", \"description\": \"Version not found\", \"errors\": null }<\/code><\/pre>\n\n\n\nIt’s not wrong, but… it’s not very helpful. We’re going to aim to make them look a bit more like this:<\/p>\n\n\n\n
{\n \"error\": \"VERSION_FORK_NOT_FOUND\",\n \"message\": \"We couldn't find the version (1.0.2) you're trying to fork from\",\n \"suggestion\": \"You need to pass an existing version (1.0.0, 1.0.1) in via the `for` parameter\",\n \"docs\": \"https:\/\/developer.example.com\/logs\/1a70daae-c1a7-11ea-b3de-0242ac130004\",\n \"help\": \"If you need help, email support@readme.io and mention log '1a70daae-c1a7-11ea-b3de-0242ac130004'.\",\n \"poem\": [\n \"This request unfortunately failed\",\n \"But hey, I guess that's life\",\n \"We couldn't find your version fork\",\n \"Or your version spoon or version knife\"\n ]\n}<\/code><\/pre>\n\n\n\nLet’s break it down.<\/p>\n\n\n\n
error<\/code>: A unique ID for every error message<\/strong><\/h2>\n\n\n\n\"error\": \"VERSION_FORK_NOT_FOUND\"<\/code><\/pre>\n\n\n\nThe nice thing about RESTful APIs is they come with built-in status codes. But the codes mean so many different things in different situations, and some are general enough that they don’t really help. <\/strong>Sure, 401 means the user is unauthorized, but why? Is their API key invalid, or is it missing? Or maybe you had a security breach and rotated everyone’s API keys? We know 404 is Not Found, but it doesn’t specify what couldn’t be found.<\/p>\n\n\n\nNormally, APIs rely on error messages like Not Found<\/code> or Bad Request<\/code> as the identifier. That makes it hard to handle specific errors in the code, so it’s good to include something more unique and specific.<\/p>\n\n\n\nYou want people to know they can check for these in the code. <\/strong>Status codes are helpful but too vague sometimes, and error messages meant for humans tend to be a bit long to check for in code. These are meant to be referenced by the code, so they should be short and immutable.<\/p>\n\n\n\nmessage:<\/code> Descriptive message of what went wrong<\/strong><\/h2>\n\n\n\n\"message\": \"We couldn't find the version (1.0.2) you're trying to fork from\"<\/code><\/pre>\n\n\n\nDon’t just explain what went wrong, tailor it to the user. <\/strong>Be as verbose as possible in diagnosing the error, so that the person reading the message knew exactly what’s going on. The error<\/code> above is for computers; this message<\/code> is for all the humans out there!<\/p>\n\n\n\nIn our API errors, we have the ability for us to include variables. So, rather than just saying \u201cthe version you specified…\u201d, we do our best to do things like show them what we\u2019re seeing (such as “the version you specified (v1.0)…”). <\/p>\n\n\n\n
Here’s some examples:<\/p>\n\n\n\n
\n- When we say your API key isn\u2019t right, we show you a few characters of what we’re seeing you sent us to help with debugging (Such as “Your API key that starts with X341 is invalid”)<\/li>\n\n\n\n
- If you don\u2019t have permission to do something, we do our best to tell you who does<\/li>\n\n\n\n
- When you pick a value that doesn\u2019t exist, we list the available things that do exist (“…you need to pick an existing version (1.0, 1.1, 1.2)…”)<\/li>\n<\/ul>\n\n\n\n
suggestion:<\/code> How to fix it<\/strong><\/h2>\n\n\n\n\"suggestion\": \"You need to pass an existing version (1.0.0, 1.0.1) in via the `for` parameter\"<\/code><\/pre>\n\n\n\nMost of the time, error messages focus on the problem and leaves it at that. How negative!<\/p>\n\n\n\n
They dutifully report what went wrong, which makes sense\u2026 but they usually stop just short of telling us what we actually<\/em> want to know, which is how to fix the problem. That\u2019s a job for Stack Overflow or something, I suppose.<\/p>\n\n\n\nAlways have a suggestion<\/code> field for every error message. <\/strong>While the message<\/code> field answers \u201cwhat\u2019s wrong\u201d, the suggestion<\/code> answers \u201chow to fix it\u201d. We don\u2019t 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.<\/p>\n\n\n\nIf there’s an issue with their API key, tell them where to find their proper API key. If they formatted something wrong, tell them how to format it correctly. If they’re missing a parameter, show them the docs for that parameter.<\/p>\n\n\n\n
Bonus:<\/em> As you’re writing these out, you’ll start to notice something: “wait, I can just fix this on the backend!” <\/strong>Rather than telling the user to send the API key as the password rather than the user via Basic Auth, just accept it in both places. Rather than telling the user to pass in a Content Type, assume it’s JSON if your API only supports JSON. Good error messages are awesome, but skipping error messages completely is even better.<\/p>\n\n\n\ndocs:<\/code> A link to more information<\/strong><\/h2>\n\n\n\n\"docs\": \"https:\/\/developer.example.com\/logs\/1a70daae-c1a7-11ea-b3de-0242ac130004\"<\/code><\/pre>\n\n\n\nIn every one of our errors, we include a link to the documentation. And not just any documentation! It’s a specific link to docs for the endpoint, and has the user’s full request embedded right in it.<\/strong><\/p>\n\n\n\nSo, not only can the user see everything about the endpoint they’re dealing with, they can also see the exact request they made. They can replay it in the UI, see what incorrect data they sent, and share the link with our support team to get more help.<\/p>\n\n\n\n
Even if you don’t have the ability to embed data into the docs, it’s still a good habit to include a link for every single error. <\/strong>It saves people from Googling, gives a clear next step for people who are stuck, and ensures there actually is a doc associated with each error.<\/p>\n\n\n\n(If this seems cool, check out the metrics included in My Developers<\/a>!)<\/p>\n\n\n\n![\"Screenshot](\"https:\/\/blog.readme.com\/content\/images\/2021\/06\/image.png\")
<\/figure>\n\n\n\nhelp:<\/code> How to contact you<\/strong><\/h2>\n\n\n\n\"help\": \"If you need help, email support@readme.io and mention log '1a70daae-c1a7-11ea-b3de-0242ac130004'.\"<\/code><\/pre>\n\n\n\nHave some sort of way to contact you. We include our email address and a way to reference each log (for example, “If you need help, email support@readme.io<\/a> and mention log ‘1a70daae-c1a7-11ea-b3de-0242ac130004′”).<\/p>\n\n\n\nYou want to give users as many ways as possible to fix their problem. <\/strong>Developers tend to prefer to figure things out themselves, however giving them explicit permission to email you will go a long way toward resolving issues quickly!<\/p>\n\n\n\npoem:<\/code> Err on the side of whimsy<\/strong><\/h2>\n\n\n\n\"poem\": [\n \"This request unfortunately failed\",\n \"But hey, I guess that's life\",\n \"We couldn't find your version fork\",\n \"Or your version spoon or version knife\"\n]<\/code><\/pre>\n\n\n\nOkay, you don’t need this one… but one of our core values<\/a> at ReadMe is to err on the side of whimsy<\/em>, and what better place to live up to it than in an error? So we wrote a unique poem for each error message:<\/p>\n\n\n\n