I have an API whose job is to aggregate resources obtained by calling multiple other APIs and then give out the aggregated response to the client. Currently even if one or more dependent API calls fail, I go ahead and aggregate response from the other dependent APIs and then give them out to the client with a 2xx status. In case all of the dependent API calls fail, I still give out a 2xx with empty list.

In case one or more dependent API calls fail, I want to give out an indication to the client. I was thinking of using the HTTP code 206. What would be the best approach to handle this scenario? Is giving out a 206 with the names of the dependent services that failed to give out a 2xx as part of a header the correct approach. If yes, what should this header be called?


Is giving out a 206 with the names of the dependent services that failed to give out a 2xx as part of a header the correct approach.

No, that is not what 206 is for. 206 is for when the client requests only part of the resource. The server can use that response to indicate that only part of the resource was returned. But this is an expected result controlled by the client. It is not due to any error taking place

In the scenario you are describing a server error has taken place, so you should return a 500 indicating to the client that something has gone wrong with the generation of the resource and there is nothing the client has done wrong (which is what 5xx errors are about)

You can return the partially generated resource in the body of the 500, although I'm not sure why you would want to do that? Is that half generated resource even relevant to the client if it is missing data?

| improve this answer | |

You should not return a success status for a partial success. This denies the caller the possibility to address the problem and potentially retry the operation. It is not a good pattern to return success and then the caller has to dig around in the error text to find out if it failed.

This is for true failure cases, in other words the service could not perform the service it was asked to do. There is a bit of a grey area, for example a search service. If the caller searches for a term that doesn't exist, the service performs the search and reports an empty result set, that's not a failure from the service's perspective. The service successfully performed the search. On the other hand, if the client requests an account for a 13-digit account number and provides only 10 digits, the service can return a 4xx error (bad request, not found). If the service runs into an exception during the work, it can return a 5xx status (server-side error).

So there can be a use case for 2xx and partial success, but I think the ambiguity is better avoided in most cases.

| improve this answer | |
  • I'd prefer a 2xx, but with a separate status field to indicate that not all resources were available. – user949300 Feb 25 at 18:33

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.