3rd party API gives back 500 error, what code should my API return

Question

I've written an API in a framework based on ZF2 (Zend Framework 2) called Apigility.

My Service can query 3rd party API's. Once in a while, I get back a 500 error message.. either due to expired tokens, or some such.

How should MY API respond back to my client?

I thought at first I should return 500, but actually that seems wrong. I don't want to return an error indicating I've crashed.. it's the 3rd party that has 500'd.

Update: below is what i'm seeing from the third party.

I think I like the idea of 503 Service unavailable.. with an error message cluing the user into what's wrong, and how to fix it.

Update showing 3rd party's response :

Error performing request to OAuth Provider. 
HTTP/1.1 500 Internal Server Error
Server: nginx/1.1.19
Date: Fri, 22 Aug 2014 20:24:40 GMT
Content-Type: text/html
Content-Length: 20
Connection: close
X-Powered-By: PHP/5.3.10-1ubuntu3.1
Set-Cookie: lang_select_language=en; Expires=Sun, 21-Aug-2016 20:24:42 GMT; Path=/
X-WI-SRV: FR-EQX-WEB-03
Vary: Accept-Encoding
Content-Encoding: gzip

Thoughts?

/**
 * Status titles for common problems
 *
 * @var array
 */
protected $problemStatusTitles = array(
    // CLIENT ERROR
    400 => 'Bad Request',
    401 => 'Unauthorized',
    402 => 'Payment Required',
    403 => 'Forbidden',
    404 => 'Not Found',
    405 => 'Method Not Allowed',
    406 => 'Not Acceptable',
    407 => 'Proxy Authentication Required',
    408 => 'Request Time-out',
    409 => 'Conflict',
    410 => 'Gone',
    411 => 'Length Required',
    412 => 'Precondition Failed',
    413 => 'Request Entity Too Large',
    414 => 'Request-URI Too Large',
    415 => 'Unsupported Media Type',
    416 => 'Requested range not satisfiable',
    417 => 'Expectation Failed',
    418 => 'I\'m a teapot',
    422 => 'Unprocessable Entity',
    423 => 'Locked',
    424 => 'Failed Dependency',
    425 => 'Unordered Collection',
    426 => 'Upgrade Required',
    428 => 'Precondition Required',
    429 => 'Too Many Requests',
    431 => 'Request Header Fields Too Large',
    // SERVER ERROR
    500 => 'Internal Server Error',
    501 => 'Not Implemented',
    502 => 'Bad Gateway',
    503 => 'Service Unavailable',
    504 => 'Gateway Time-out',
    505 => 'HTTP Version not supported',
    506 => 'Variant Also Negotiates',
    507 => 'Insufficient Storage',
    508 => 'Loop Detected',
    511 => 'Network Authentication Required',
);

Ardeha

It really depends on what your API consumers expect. Do your API results include an error field? – Astronomer

@Mr.Llama I'll update with an example response the 3rd party gives me. I'm thinking I need a way to say in REST, 'hi, I got your request, and forwarded it, but it failed, and here's why..' We already include an error field as well.. – Ardeha

Answer 1

Well, I think it's up to you which error code you'll use. But if the actual functionality of your API depends on a third-party API, I would consider using the HTTP code 503 Service Unavailable, because your service will be unavailable until the third-party API works, no matter what HTTP code the third-party API returned. I would also include some details (error message) in the response payload.

Or you can return the HTTP code 200 OK and send the custom error code and message as the response payload, of course, because the HTTP request to your API was actually successful. But I would prefer to use the HTTP code to indicate the state of your API endpoint.

I would mirror the HTTP codes from a third-party API to the user only in case your API acts as a proxy without any additional functionality.

Secede

200 is unacceptable, since the user is expecting an action to occur (and get some data back) I'm thinking I'll do 400.. or 503, thank you for the reminder – Ardeha

But you should think about HTTP code you are returning as a code describing the request between user and you. If you return HTTP 400, I'll understand, that I'm doing my request wrong and will be trying to fix it. – Valdovinos

I don't think returning 400 would serve the purpose. I think returning status code 503 would be good option. – Benita

@Benita You just repeated what I wrote but without any explanation. – Valdovinos

@DawidFerenczy I was looking for something similar to return a relevant response when one of the 3rd party api is down. Yeah I agreed with you and simply second your point that it will make more sense to return 503. This is how I've implemented. – Benita

2xx is not acceptable, as the request hasn't been fulfilled correctly. – Petronel

@DavidFerenczyRogožan, returning a 400 does not mean you are doing your request wrong. It means you might do your request wrong. See the 403 error for example. Detailed explanation in my answer below. 400 should be the http code returned here with a json data telling the client to retry. – Overnight

Answer 2

When a client calls your API does it specify directly or indirectly that it wants your API to communicate with the 3rd party service?

• No - then for the client it will be 500, as it is still Internal Server Error from the client's perspective. Unless your API can interpret the error message from 3rd party service and derive a more specific error code.

• Yes - then 503 seems to be the most appropriate here. The error message may specify what service is unavailable.

Sogdiana

It directly requests that 3rd party, by name. – Ardeha

Answer 3

I think the first step here would be to identify the range. A 4xx would mean the User has the chance to fix the request, which is not the case here. 2xx sounds incorrect too, as the request is not successful. That leaves us pretty much with something in the range of the 5xx.

In the 5xx range, two options look appropriate to me. A simple 500 would be fine: "There is an unspecified Server Error". 503 sounds good as well, meaning "We cannot fulfill this right now, but will be able to do so later on (optionally specify the retry span in a header).

Petronel

Answer 4

Using a 5xx is not the right thing to do as your server behaves correctly, and the route called also.

You simply cannot deliver an expected data for now.

If a third party sends a 503 (for maintenance for example), your server on the contrary is not in maintenance, and can trigger a retry policy.

If after the retry, there is still a 503, you can respond with a 400 and send data to retry after a moment.

400 is the only http code that could make sense. There are no 4xx http code for this kind of issue.

4xx are errors where client may have send incorrect data. In this case, and like for 403, client does not send incorrect data. So a 400 is suitable.

449 could also be used, if the client has an option to bypass the third party service or use another one. But beware, it is Microsoft specific.

503 makes sense only if your route acts as a proxy.

2xx does not make sense ever here.

Overnight

Answer 5

Per RFC 9110 ("HTTP Semantics") HTTP 502 is the right way to go:

The 502 (Bad Gateway) status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.

Memnon