REST API error return good practices

web-services http rest
Remus Rusanu picture Remus Rusanu · Jun 3, 2009 · Viewed 276.5k times · Source

I'm looking for guidance on good practices when it comes to return errors from a REST API. I'm working on a new API so I can take it any direction right now. My content type is XML at the moment, but I plan to support JSON in future.

I am now adding some error cases, like for instance a client attempts to add a new resource but has exceeded his storage quota. I am already handling certain error cases with HTTP status codes (401 for authentication, 403 for authorization and 404 for plain bad request URIs). I looked over the blessed HTTP error codes but none of the 400-417 range seems right to report application specific errors. So at first I was tempted to return my application error with 200 OK and a specific XML payload (ie. Pay us more and you'll get the storage you need!) but I stopped to think about it and it seems to soapy (/shrug in horror). Besides it feels like I'm splitting the error responses into distinct cases, as some are http status code driven and other are content driven.

So what is the industry recommendations? Good practices (please explain why!) and also, from a client pov, what kind of error handling in the REST API makes life easier for the client code?

Answer

Omar Ali picture Omar Ali · Dec 17, 2015

A great resource to pick the correct HTTP error code for your API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

An excerpt from the article:

Where to start:

enter image description here

2XX/3XX:

enter image description here

4XX:

enter image description here

5XX:

enter image description here

Related questions

SOAP vs REST (differences)

I have read articles about the differences between SOAP and REST as a web service communication protocol, but I think that the biggest advantages for REST over SOAP are: REST is more dynamic, no need to create and update UDDI(…

Read More
REST API 404: Bad URI, or Missing Resource?

I'm building a REST API, but I've encountered a problem. It seems that accepted practice in designing a REST API is that if the resource requested doesn't exist, a 404 is returned. However, to me, this adds unnecessary ambiguity. HTTP 404 is …

Read More
RESTfully design /login or /register resources?

I was designing a web app and then stopped to think about how my api should be designed as a RESTful web service. For now, most of my URI's are generic and might apply to various web apps: GET /logout // …

Read More