What are REST API error handling best practices?

1 like

Please login to like this article.

What is REST API error handling best practices?

I wouldn't return a 200 unless there really was nothing wrong with the request. From RFC2616, 200 means "the request has succeeded."

If the client's storage quota has been exceeded (for whatever reason), I'd return a 403 (Forbidden):

This tells the client that the request was OK, but that it failed (something a 200 doesn't do). This also gives you the opportunity to explain the problem (and its solution) in the response body.

What other specific error conditions?

The main choice is done you want to treat the HTTP status code as part of your REST API or not.

Both ways work fine. I agree that strictly speaking, one of the ideas of REST is that you should use the HTTP Status code as a part of your API (return 200 or 201 for a successful operation and a 4xx or 5xx depending on various error cases.) However, there is no REST police. You can do what you want. I have seen far more egregious non-REST APIs being called "RESTful."

At this point (August 2015) I do recommend that you use the HTTP Status code as part of your API. It is now much easier to see the return code when using frameworks than it was in the past. In particular, it is now easier to see the non-200 return case and the body of non-200 responses than it was in the past.

The HTTP Status code is part of your API

You will need to carefully pick 4xx codes that fit your error conditions. You can include a rest, XML, or plaintext message as the payload that includes a sub-code and a descriptive comment.
The clients will need to use a software framework that enables them to get to the HTTP-level status code. Usually doable, not always straightforward.
The clients will have to distinguish between HTTP status codes that indicate a communications error and your own status codes that indicate an application-level issue.
The HTTP Status code is NOT part of your API

The HTTP status code will always be 200 if your app received the request and then responded (both success and error cases)

All of your responses should include "envelope" or "header" information. Typically something like:

envelope_ver: 1.0
status:  # use any codes you like. Reserve a code for success. 
msg: "ok" # A human string that reflects the code. Useful for debugging.
data: ...  # The data of the response, if any.

This method can be easier for clients since the status for the response is always in the same place (no sub-codes needed), no limits on the codes, and no need to fetch the HTTP-level status code.

Main issues:

Be sure to include version numbers so you can later change the semantics of the api if needed.
Document

Do remember that 5xx errors are server-side, aka the client cannot change anything to its request to make the request pass. If the client's quota is exceeded, that's definitely not a server error, so 5xx should be avoided.

This is extremely late to the party, but now, in the year 2013, we have a few media types to cover error handling in a common distributed (RESTful) fashion. See "vnd.error", application/vnd.error+json (https://github.com/blongden/vnd.error) and "Problem Details for HTTP APIs", application/problem+json (https://datatracker.ietf.org/doc/html/draft-nottingham-http-problem-05).

There are two sorts of errors. Application errors and HTTP errors. The HTTP errors are just to let your AJAX handler know that things went fine and should not be used for anything else.

`5xx` Server Error

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx Success

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

However, how you design your application errors is really up to you. Stack Overflow for example sends out an object with response, data and message properties. The response I believe contains true or false to indicate if the operation was successful (usually for write operations). The data contains the payload (usually for read operations) and the message contains any additional metadata or useful messages (such as error messages when the response is false).

Agreed. The basic philosophy of REST is to use the web infrastructure. The HTTP Status codes are the messaging framework that allows parties to communicate with each other without increasing the HTTP payload. They are already established universal codes conveying the status of the response, and therefore, to be truly RESTful, the applications must use this framework to communicate the response status.

Sending an error response in an HTTP 200 envelope is misleading, and forces the client (API consumer) to parse the message, most likely in a non-standard, or proprietary way. This is also not efficient - you will force your clients to parse the HTTP payload every single time to understand the "real" response status. This increases processing, adds latency, and creates an environment for the client to make mistakes.

Don't forget the 5xx errors as well for application errors.

In this case what about 409 (Conflict)? This assumes that the user can fix the problem by deleting stored resources.

Otherwise, 507 (not entirely standard) may also work. I wouldn't use 200 unless you use 200 for errors in general.

If the client quota is exceeded it is a server error, avoid 5xx in this instance.