5

My web application calls a third party API.

If I successfully call the API but invalid data is returned which cannot be processed by my system what is the most appropriate HttpCode to return to the user calling me?

  • 500, I'm not convinced. Although it was an internal error it's due to external factors
  • 503, Perhaps, although very vague
  • 400, 4XX errors are usually related to the client contacting our server and so could be misleading.

Which is the most appropriate response to return to my client?

6
  • So the third-party API waits for you to output an HTTP status code? If yes, you have to look at their API documentation to see how to handle it. Here it doesn't matter what you prefer, take a look at their API and choose a proper status code.
    – Mahdi
    Mar 19, 2014 at 10:55
  • @Mahdi it's more the status code I return to my user (which I can define). I've updated the question to try to make this clearer
    – Liath
    Mar 19, 2014 at 10:57
  • 1
    Yes, I see. In that case I will go for 500, however your users might blame on you for the error. I'd output a proper page -- 200 code, informing them about the third-party call failure and will ask them to try it again later.
    – Mahdi
    Mar 19, 2014 at 11:00
  • 2
    For your clients, how relevant would the difference be between an internal error in your implementation or an error due to external factors? Mar 19, 2014 at 11:00
  • 1
    @Mahdi There's nothing stopping a 500 error from including content with more information.
    – Brian
    Mar 19, 2014 at 13:33

1 Answer 1

11

If the problem is not the user / client's fault then your server should return a 5xx error. A 4xx error should only be returned if the >>request<< is incorrect in some way.

Depending on the situation, either 500 or 503 could be appropriate:

  • As far as a client is concerned the "external factors" are internal to your server / service. So 500 could be appropriate.

  • If the problem is likely to resolve itself (or be resolved) in a relatively short period of time, 503 could be appropriate.

Probably either of those is OK.

Another possibility is to return a non-standard 5xx code. Note that non-standard (i.e. not defined in the HTTP 1.1 spec) status codes are not wrong. There is ample precedent for doing this ... including the precedent of other RFCs defining extra codes; see the Wikipedia List of HTTP Status Codes for examples.


I noticed a comment suggesting this:

In that case I will go for 500, however your users might blame on you for the error.

Provided that you include details of the cause of the problem in the 500 response body (in an appropriate format!), that should not be a problem.

I'd output a proper page -- 200 code, informing them about the third-party call failure and will ask them to try it again later.

IMO, that is incorrect. A 200 code means that the request has succeeded ... which it patently hasn't. Assuming that this is a RESTful service, the client is going to use the status code to decide what to do next. It should not be a lie. If you want to say "try again later", you should send a 503 response, possibly with a Retry-After header.

1
  • I think you're right - whether we expect the issue to resolve itself (unavailablity) is the key factor
    – Liath
    Mar 19, 2014 at 11:05

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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