REST API error return good practices

Question

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

User · Answer

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

User · Answer

Remember there are more status codes than those defined in the HTTP 1 1 RFCs  the IANA registry is at http   www iana org assignments http-status-codes  For the case you mentioned status code 507 sounds right

User · Answer

I know this is extremely late to the party  but now  in 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   tools ietf org html draft-nottingham-http-problem-05

User · Answer

Modeling your api on existing  best practices  might be the way to go  For example  here is how Twitter handles error codes https   developer twitter com en docs basics response-codes

User · Answer

Please stick to the semantics of protocol  Use 2xx for successful responses and 4xx   5xx for error responses - be it your business exceptions or other  Had using 2xx for any response been the intended use case in the protocol  they would not have other status codes in the first place

User · Answer

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

User · Answer

The main choice is do 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 are 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 at the HTTP-level status code  Usually do-able  not always straight-forward  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  no need to fetch the HTTP-level status-code    Here s a post with a similar idea  http   yuiblog com blog 2008 10 15 datatable-260-part-one   Main issues    Be sure to include version numbers so you can later change the semantics of the api if needed  Document

User · Answer

As others have pointed  having a response entity in an error code is perfectly allowable   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 definitly not a server error  so 5xx should be avoided

User · Answer

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 response  and therefore  to be truly RESTful  the applications must use this framework to communicate the response status    Sending an error response in a 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

User · Answer

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     2XX 3XX     4XX     5XX

User · Answer

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     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       The server understood the request  but is refusing to fulfill it  Authorization will not help and the request SHOULD NOT be repeated  If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled  it SHOULD describe the reason for the refusal in the entity  If the server does not wish to make this information available to the client  the status code 404  Not Found  can be used instead    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 did you have in mind

User · Answer

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

[web-services] REST API error return good practices

`5xx` Server Error

2xx Success

Examples related to web-services

Examples related to http

Examples related to rest