I am designing an application that interacts with a RESTful API.

When returning error messages like Unable to sign up user

Should the error message be generated by the app? or by the API? I am looking for best practices.

  • 1
    Don't you need both? The API needs to display an error, and the app needs to handle the error. Are you just worried about who generates the error wording? Jul 10, 2013 at 19:39
  • Yes, I am worried about who generates the error message wording. Jul 10, 2013 at 21:10

4 Answers 4


At the very least, the REST api needs to return an error code (e.g. 123) and/or an error key (e.g. "cannotRegister") which the application can then pick up in order to display a related message. This also helps when you're dealing with an application that is available in multiple languages. The app can then pick the related message from the appropriate resource bundle (translation). The API doesn't need to know in what language the user is viewing the application.

  • 4
    globalization is the end-all reason literation should always be in the UI. Even outside of globalization though, the UI should be the owner of all things that matter only to users and not to logic. Jul 10, 2013 at 20:53
  • @JimmyHoffa Careful, if you have a public REST API, then you might want to provide a good error description to your API consumers, on top of some error code that might not be descriptive enough. Jul 17, 2019 at 6:45

I try to handle as many errors as possible by the API. In environments with multiple clients this helps to keep things consistent and easier to maintain.

When performing the error handling via the API the mere status code is defintely not enough. The approach I take here, is to provide an additional error response body that also provides a human readable message as well as a more detailed message for the developer and a link to further resources that provide some extra explanation. In JSON this could look something like this:

    "status": 404,
    "code": 404-07,
    "message": "Ooops! Seems like the file does not exist.",
    "developerMessage": "File resource for path /uploads/foobar.txt does not exist.",
    "moreInfo": "http://www.mycompany.com/errors/404-07"

Example taken from stormpath.

The clients then use the human readable message and directly present them to the end user.

To handle i18n we use the HTTP Accept-Language and Content-Language headers. The error messages then get delivered in the desired language.

  • Since "Ooops! Seems like the file does not exist." is not something that I would ever display to English speaking users, much less non-English users, that kind of parameter is rather pointless.
    – gnasher729
    May 27, 2015 at 12:40
  • 1
    The content of the parameter is set dynamically. Of course you could customize your message to something more serious ;-) Also, as I mentioned in the response you can use HTTP-Headers to determine the language of the requesting user.
    – benjiman
    May 28, 2015 at 18:57
  • "code": 404-07 good idea... but not an integer, it's more like a string code. So need more operations to done here. Maybe 40407 Jun 8, 2020 at 12:16

The API should do whatever it can to give the application the necessary information how to proceed. But for the user, the message is most likely:

None - for things like updates, prefetch etc. or where retrying helps.
Tell them "it didn't work".
Tell them "it didn't work, it might work later".
Tell them "it didn't work, here's what you can do to fix it"
Tell them "it didn't work, give this cryptic information to the help desk". 

But it's up to the application to decide there, based on the situation and the information from the server. The server cannot know what a suitable message for the user would be.


Simply put an error page url in your configuration file (web.config if asp.net), that displays the error page in case if an error has occured.

Using the api? never heard of it, but if it is global enough to trigger a message on any error, then may be it is good enough..

Use the app's configuration to trigger a custome error. If you cant use your own code, but put it somewhere that responds to any request , no matter what type of request, otherwise you will have errors slipping by!

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.