REST API - best method for error handling

Question

When constructing an API response, which method is better for (manually) returning the status code to indicate the validity of the request:

1 - Embed a response code within the JSON response

{
  'status_code' => 200,
  'status_message' => 'OK',
  'data' => { ... }
}

2 - Or is it better to modify the HTTP Headers Status field?

Request URL:http://somesite.com
Request Method:GET
Status Code: 200 (EDITING THIS ONE)

I would think that the HTTP Statuses should only be regarding connection errors and file retrieval errors that occur at the server level rather than altering this to address application level errors.

Any good articles and resources to read would be very appreciated as well.

score 2 · Accepted Answer · answered Nov 24 '11 at 03:34

2

I have found the best way to present errors in a REST Request is to change the HTTP Status Code to the proper error, and embed the error in the response.

If you are using JSON, it might look like this, with the status code set to 500 for this example:

{"error" : "An error has occurred while trying to read from the database."}

This is the same method that Microsoft CRM uses to report errors, and it has proved to be a good method; RESTFul applications will not fail to parse the response if they are expecting JSON (or XML, if you are using that).

answered Nov 24 '11 at 03:34

Nick Garvey

2,980
24
31

Does a status code of 500 allow for body content to be passed back? – Atticus Nov 24 '11 at 04:17
1

Yup. You can actually put body content on any status code, you just shouldn't for several status codes (204 No Content being an obvious example). – Nick Garvey Nov 24 '11 at 04:25

score 1 · Answer 2 · edited May 23 '17 at 12:27

This question addresses the same issue (perhaps from a slightly different perspective).

I think that, in general, if a request to a resource in your application results in an error condition, that fact should be reflected in the HTTP headers. You can use the application response to provide more detailed information.

Update: Here is an interesting mapping of application errors to status codes (used by Azure).

REST API - best method for error handling

2 Answers2