Best Practice: Should error messages be handled by the API or by the App?

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

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.

Answer 4

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!