HTTP status code for a partial successful request

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

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.

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.

I needed the same issue and after reading a bit of the documentation, the best solution to this problem seems to respond with an non-standard 2xx response. A generic client will treat this as success but a specific client can understand what has happened. You may also support this with custom headers in form X-failed: thispart code. You probably should include what is the problem with the operation as text so that generic clients will be able to display nature of what has happened. Here is what I have done where a file is uploaded but the processing cannot be done at this moment:

HTTP/1.1 210 Partial success
X-failed: processing
X-reason: server busy

File has been uploaded, however, the task associated with the 
file has not started as the server is busy. Re-request processing
at a later time.

What about using 206 Partial Content. I know 206 is more about ranges, but what if it could indicate a partially successfully request?

The HyperText Transfer Protocol deals with the transmission side of things. It doesn't have error codes to deal with application level errors.

Returning 200 is the right thing to do here. As far as HTTP is concerned the request was received properly, handled properly and you're sending the response back. So, on the HTTP level everything is OK. Any errors or warnings related to the application which running on top of http should be inside the response. Doing so will also prevent some nasty issues you might run into with proxy servers which might not handle certain responses the way you expect.