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', ); 

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 3rd party API, I would consider using the HTTP code 503 Service Unavailable, because your service will be unavailable until the 3rd party API won't work, no matter what HTTP code the 3rd 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 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 3rd party API to the user only in case your API acts as a proxy without any additional functionality.

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.