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

Question

I am building an API where the user can ask the server to perform multiple actions in one HTTP request. The result is returned as a JSON array, with one entry per action.

Each of these actions might fail or succeed independently of each other. For instance, the first action might succeed, the input to the second action might be poorly formatted and fail to validate and the third action might cause an unexpected error.

If there was one request per action, I would return status codes 200, 422 and 500 respectively. But now when there is only one request, what status code should I return?

Some options:

• Always return 200, and give more detailed information in the body.
• Maybe follow the above rule only when there is more than one action in the request?
• Maybe return 200 if all requests succeed, otherwise 500 (or some other code)?
• Just use one request per action, and accept the extra overhead.
• Something completely different?

Answer 1

The short, direct answer

Since the request speaks of executing the list of tasks (tasks are the resource that we're speaking of here), then if the task group has been moved forward to execution (that is, regardless of execution result), then it would be sensible that the response status will be 200 OK. Otherwise, if there was a problem that would prevent execution of the task group, such as failing validation of the task objects, or some required service isn't available for example, then the response status should denote that error. Past that, when execution of the tasks commences, seeing as the tasks to perform are listed in the request body, then I would expect that the execution results will be listed in the response body.

---

The long, philosophical answer

I suspect that you are experiencing this dilemma because you are diverting from what HTTP was designed for. I suspect that you are attempting to use it as means of RMI (Remote Method Invocation) rather than as means to manage resources.

The RMI perspective is that you would design your URI scheme as you would functions in an application, and upon request, these would execute an action, and then return its result. Although these types of implementations are relatively common still, these often produce situations HTTP is in the way, rather than making things easy.

(Just to note, RMI through HTTP has its merits in some instances, though you'd still be wise to implement these methods in a non-blocking manner. You could maybe offer startTask and getTaskStatus for instance, both of which would return instantly.)

The design of HTTP is asking you to use it to manage resources instead. It wants to express things like "add a task" (via POST), "get a task" (via GET), "delete a task" (via DELETE) and so on. Designing our URI scheme in that way, we rarely find ourselves in conflict with what HTTP has to offer.

To provide an example of what I mean by a URI scheme that conforms to resource management (vs RMI), here's a layout that might work for your case:

• /task?complete=[true/false]&start=[start_timestamp]&end=[end_timestamp] ...
  • GET searches for tasks according to querystring
  • POST adds a single task
• /task/[id]
  • GET responds with a single task's state object
• /task/[id]/cancellation_request
  • POST adds a cancellation request for the task.
• /task/[id]/[property_name]
  • GET returns the value of the property of a task of the specified id
• /task_group?complete=[true/false]&start=[start_timestamp]&end=[end_timestamp] ...
  • GET searches for task groups according to querystring
  • POST adds a group of tasks
• /task_group/[id]
  • GET responds with a task group object, which includes a list of task objects of all of the tasks in the group.

... and so on

As you may have guessed, task execution in this scheme would be an asynchronous thing -- POST to /task would not wait until the task has completed, or even until it actually started running -- It would simply queue it for execution and then respond that it succeeded to add that task, or that it failed, if the queue is full, for instance.

Note how the URIs have no verbs in them -- They represent resources or collections of resources. The only verbs in this entire scheme are the HTTP methods that are invoked upon these URIs (GET/POST in this case).

Just to hammer this in a little more, URI stands for "Unified Resource Identifier".

---

Examples of how the above URI scheme would be used

Executing a single task and tracking progress:

• POST /task with the task to execute
• GET /task/[id] until response object complete has positive value while showing current status/progress. You can also implement updates with websocket if you want to avoid polling.

Executing a task group and tracking progress:

• POST /task_group with the group of tasks to execute
• GET /task_group/[groupId] until response object complete property has positive value, showing individual task status (3 tasks completed out of 5, for example)

Answer 2

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.

Answer 3

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.

Answer 4

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

Answer 5

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.

Answer 6

Already many good answers here, but one aspect is missing:

What's the contract that your clients expect?

HTTP return codes should indicate at least a success / failure distinction and thus play the role of "poor man's exceptions". Then 200 means "contract completely fulfilled", and 4xx or 5xx indicate failure to fulfill.

Naively, I'd expect the contract of your multiple-actions request to be "do all my tasks", and if one of them fails, then the request wasn't (completely) successful. Typically, as a client I'd understand 200 as "everything ok", and codes from the 400 and 500 family force me to think about the consequences of a (partial) failure. So, use 200 for "all tasks done" and 500 plus a descriptive response in case of a partial failure.

A different hypothetical contract might be "try doing all of the actions". Then it's completely in line with the contract if (some of) the actions fail. So you'd always return 200 plus a results document where you find the success / failure information for the individual tasks.

So, what's the contract you want to follow? Both are valid, but the first one (200 only in case everything was done) is more intuitive to me, and better in line with typical software patterns. And for the (hopefully) majority of cases where the service completed all tasks, it's straightforward for the client to detect that case.

A final important aspect: How do you communicate your contract decision to your clients? E.g. in Java, I'd use method names like "doAll()" or "tryToDoAll()". In HTTP, you can name the endpoint URLs accordingly, hoping that your client developers see, read, and understand the naming (I wouldn't bet on that). One more reason to choose the contract of least surprise.

Answer 7

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.

Answer 8

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.