HTTP status code for a partial successful request

Question

I have an application that sends messages to users. In a post request a XML string is transferred that consists of all the users that should receive that particular message. If any of the users in the list do not exist I give the list of missing users back to the client for further evaluation.

Now I'm asking myself what would be the proper status code for the application saying that the request was accepted but there were things that couldn't be done.

The problem would be avoided if it weren't allowed to include missing users in the list. Then the sending attempt would just get an 4xx error. But there is no point in forming the API this way. On the other hand I could consider the error condition to be purely application specific. But sending a 200 just does not feel right. And it would be nice to give the client a hint when to look deeply in the error response. e.g. to avoid sending messages to that users over and over

Solution 1

I've dealt with a very similar issue. In this case, I returned a

207 Multi-Status

Now, this isn't strict HTTP, it's part of the WebDAV extension, so if you don't have control over the client too, then this isn't good for you. If you do, you could do something like so:

   <?xml version="1.0" encoding="utf-8" ?>
   <D:multistatus xmlns:D='DAV:'>
     <D:response>
       <D:user>user-123</D:user>
       <D:status>success</D:status>
     </D:response>
     <D:response>
       <D:user>user-789</D:user>
       <D:status>failure</D:status>
     </D:response>
   </D:multistatus>

But again, this is an HTTP extension, and you need to have control of the client as well.

Solution 2

I've had the same problem, and I've ended up using two different solutions:

• HTTP return code 202: Accepted, indicating that the request was ok, but there's no guarantee everything actually went as it should.
• Return a normal 200 in the response, but include a list of what didn't pan out in the response body.

The second one usually works best, but the first one is great if you're lazy or use a queue for processing.

Comments

[Norbert Hartl]

HTTP is an application level protocol. You cannot put it simply on transport and application level. If you think about OSI then HTTP is on layers 5-7. HTTP is somewhat different. Most of the headers and return codes are indeed application specific. The codes just depend on the information given in the HTTP protocol entities and not on custom application format things. Regarding the 200 I would say that your definition is purely wrong if it is applied to verbs not being POST. But POST changes the game a little bit and in this context your assumption "handled properly" is not sure, either

[AVee]

Stricly speaking OSI considers HTTP a application level protocol and when talking to a 'normal' webserver this is true. But in your case you are running your own protocol on top of HTTP, like lots of applications do these days. In that type of usage HTTP just provides the transport. (Your application is sending messages to users, not transferring hypertext...)

[Norbert Hartl]

Just to be clear. HTTP in a REST way is resource centric. In this context 200 means identity (the resource you specified) instead of 3xx which points in direction of the identity. Using POST turns the resource URI into a processing URI and there error codes need to cope with that. The context shifts a bit and the defintion of things get a bit blurry or at least hard to understand

[AVee]

The context shift also means there are no suitable error codes, since the protocol was never designed with that context in mind ;-) I also think you should be careful with using error codes since proxy servers tend to run with them replacing your response with a custom error page, this can be a real PITA.

[Norbert Hartl]

Where is the difference between sending messages and transferring hypertext? These are just invocations of the entity(URI) with a verb(http method) and meta-data(headers etc.). It becomes hypertext when you add the corresponing Content-Type header otherwise there is no single difference.

[Norbert Hartl]

I think the error codes are still suitable if you are using POST. It is just a lot harder not to make mistakes about the context your are serving. So I'm still not convinced what is the best thing to do :) But I'm sure I won't weaken my own software just to cover the broken behaviour of a proxy.

[Norbert Hartl]

Anyway, thanks for answering my question. I just discovered stackoverflow is bad chat client :)

[Norbert Hartl]

I thought about using this but I wasn't quite comfortable with it. Thanks!

[Kylar]

The nice thing about it is that you can return as much or little of pertinent data as you want - which is especially useful for mixed-data sets, i.e.: where some fail and some pass.

[Norbert Hartl]

I understand. I'm just trying to avoid an extra level of status handling (which is not nice IMHO). Most of my code works with HTTP ones. And I think my described use case will do fine without.

[Kylar]

You can always send a body back - send a 200 with a JSON response or whatever you want in it to determine which ones were successful.

[Norbert Hartl]

Yes, I know. But if you return a body you need to parse it. And at that moment you introduce a second layer of application logic handling. This raises complexity and you need a good reason to do it then.

[Batman]

Technically TCP is the protocol that deals with the transmission of things. HTTP can be and should be used well to indicate and understand the response if an API. a 200 with an error code is not of much use. As its specifically part of the OK responses suggested by the HTTP RFC.

[Sinaesthetic]

Isn't 202 referring more to something like queueing?

[sbbs]

MDN states as follows: "The HTTP 206 Partial Content success status response code indicates that the request has succeeded and has the body contains the requested ranges of data, as described in the Range header of the request." As far as I understand, 206 Partial Content is strictly for requests with a content range.

[Erico]

Yes, @Sinaesthetic. From the most recent HTTP 1.1 spec, "(...) the request has been accepted for processing, but the processing has not been completed". So, for partial success, 202 is not appropriate.

[Allison]

The W3C RFC doc also specifies that 206 is for a partially-fulfilled GET request, not POST. The server has fulfilled the partial GET request for the resource. The request MUST have included a Range header field (section 14.35) indicating the desired range, and MAY have included an If-Range header field (section 14.27) to make the request conditional. w3.org/Protocols/rfc2616/rfc2616-sec10.html

[Palec]

IMO 200 explicitly allows for partial success as the intended meaning of the payload is specified as status for POST, PUT and DELETE. tools.ietf.org/html/rfc7231#section-6.3.1 Status 202 is successful start of an asynchronous call whose result is not known yet. Similar to getting a promise/future. The response should tell how to get the actual result or at least monitor the status.

[Charlie Reitzel]

HTTP is the "application" only with respect to the TLS over TCP/IP "transport". To the REST service "application" (or a web UI or ...), HTTP(S) can be considered a transport. Mapping HTTP methods and response codes to application semantics is always an approximation. REST provides a set of guidelines for that mapping. But application designers can and should diverge from these guidelines when necessary to deliver on application requirements.

[Dmitry Naumov]

207 Status Code Reference