What HTTP status code to return if multiple actions finish with different statuses?

My vote would be to split these tasks into separate requests. However if too many round trips are a concern, I did come across HTTP response code 207 - Multi-Status

Copy/paste from this link:

A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate. The default Multi-Status response body is a text/xml or application/xml HTTP entity with a 'multistatus' root element. Further elements contain 200, 300, 400, and 500 series status codes generated during the method invocation. 100 series status codes SHOULD NOT be recorded in a 'response' XML element.

Although '207' is used as the overall response status code, the recipient needs to consult the contents of the multistatus response body for further information about the success or failure of the method execution. The response MAY be used in success, partial success and also in failure situations.

Allthough multi-status is an option, I would return 200 (All is well) if all requests succeeded and an error (500 or maybe 207) otherwise.

The standard case should usually be 200 - everything works. And clients should only have to check for that. And only if the error-case happened you can return a 500 (or a 207). I think the 207 is a valid choice in the case of at least one error, but if you see the whole package as one transaction you could also send 500. - The client will want to interpret the error-message either way.

Why not always send 207 ? - Because standard cases should be easy and standard. While exceptional cases can be exceptional. A client should only have to read the response body and do further complex decisions, if an exceptional situation warrants it.

One option would be to always return a status code 200 and then return specific errors in your JSON document body. This is exactly how some APIs are designed (they always return a status code 200 and dispatch the error in the body). For more details about the different approaches, see http://archive.oreilly.com/pub/post/restful_error_handling.html

I think neilsimp1 is correct, but I would recommend a redesign of the data being sent in such a way that you could send a 206 - Accepted and process the data later. Perhaps with callbacks.

The problem with trying to send multiple actions in a single request is exactly the fact that each action should have it's own "status"

Looking at importing a CSV (I know not really what the OP is about but it is a simple version). POST the CSV and get back a 206. Then later the CSV can be imported and you can get the status of the import with a GET (200) against a URL that shows per row errors.

POST /imports/ -> 206
GET  /imports/1 -> 200
GET  /imports/1/errors -> 200 -> Has a list of errors

This same pattern can be applied to many batch opterations

POST /operations/ -> 206
GET  /operations/1 -> 200
GET  /operations/1/errors -> 200 - > Has a list of errors.

The code that handles the POST need only verify that the format of the operations data is valid. Then at some later time the operations may be executed. In a back ground worker, so you can scale easier, for example. Then you can check the status of the operations when ever you want. You can use polling or call backs, or streams or whatever to address the need to know when a set of operations complete.

Semantically speaking, the HTTP request speaks of performing a group of tasks -- That request did not fail if the task group got to an attempt at execution (even if the execution of some or all individual tasks failed).

Therefore, if the task group executed (with disregard to failure or success of its individual tasks), that would be HTTP status 200 for that request. If for some reason the task group could not have been executed, then you return an HTTP status to convey the failure of the request. For example, if in order to execute any task you require a certain resource that isn't available, or if the request format isn't correct -- Then that would reflect a failure to make an attempt of execution of the entire group.

Since you've specified the tasks in the request body, then it would make sense that you return the execution results in the response body as well.

Answer:

Just use one request per action, and accept the extra overhead.

A status code describes the status of one operation. Therefore, it makes sense to have one operation per request.

Multiple independent operations breaks the principal that the request-response model and status codes are based on. You're fighting nature.

HTTP/1.1 and HTTP/2 have made overhead of HTTP requests far lower. I estimate there are very few situations where batching independent requests is advisable.

That said,

(1) You can make multiple modifications with a PATCH request (RFC 5789). However, this requires that the changes for not independent; they are applied atomically (all or nothing).

(2) Others have pointed out the 207 Multi-Status code. However, this is defined only for WebDAV (RFC 4918), an extension of HTTP.

The 207 (Multi-Status) status code provides status for multiple independent operations (see Section 13 for more information).

...

A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate. The 'multistatus' root [XML] element holds zero or more 'response' elements in any order, each with information about an individual resource.

An 207 WebDAV XML response would be as odd as a duck in a a non-WebDAV API. Don't do this.

If you really need to have multiple actions in one request, why not wrap all of the actions in a transaction in the backend? That way they either all succeed or all fail.

As a client using the API, I can deal with complete success or failure on an API call. Partial success is hard to deal with, since I would have to handle all of the possible resulting states.