Should a REST API return exception in response body?

Question

What is the best practice in .NET with Web API? Especially Web REST API. Should a REST API return exception in response body when an exception happens?

For sure I will return a 500 or similar HTTP status. But when I response with this error code what are the best practice? Or even better what is the specification or REST API about this?

• return the exception (what I do)
• return en empty response body? (yes but we lose information that can help for debuging)
• return an empty of default JSON object? (I find this confusing)
• something else?

Answer 1

return the exception (what I do) -> You should not return the exception as is because: 1) It may contain information that you would not want to be exposed to the users of your REST API. For instance consider file paths in case of an IO exception or sql server information in case of an sql exception, so on. 2) You will be sending information that is not needed by the clients of REST API, thus wasting bandwidth and serializing unnecessary information.

return en empty response body? -> No.

return an empty of default JSON object? -> No.

something else? -> Return a very specific error message (plus any other information that you think could be helpful for the developers who are integrating that REST API for resolving that error or for you to trace that error if you are provided with that error message. After all you will have to look into some issue at some point so make sure that the information you pass is enough to give you an idea about what went wrong).

Answer 2

I have this suggestion.

• The error needs to be handled by some Filter in your application (API). This Filter will get the unexpected error, transform the error in a JSON with http status code equals 500.

• The returned error needs to have the same JSON format, like this:

   { code: 12321312, message: "A fatal error occurred", details: "An unexpected information was passed as parameter to the API." } 

• The error format needs to be something informative. When you get the error in the Filter, you can save the error in database with a generated code (the error code, like an UUID) and return the code in the JSON. To have a nice API, the use of error codes will be a good feature and will help you to identify the problems.

Answer 3

By all means YES you should include a representation of the exception in the body of the response. The exception will be the best explanation of what is wrong, and it will be the most helpful to aid the user in correcting whatever went wrong. I recommend a response code of 400 for all errors, however any number in the 400 range is acceptable.

I did some research and found that the most common/standard uses a JSON structure of this form:

{
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

Many of these are optional, but there in case you need them. The important thing about this structure is that the error is described in an object under the member "error".

This is the format proposed by the OASIS data standard OASIS OData and seems to be the most standard option out there, however there does not seem to be high adoption rates of any standard at this point.

The details are discussed in my blog post on Error Handling in JSON REST API