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
Error performing request to OAuth Provider.
HTTP/1.1 500 Internal Server Error
Date: Fri, 22 Aug 2014 20:24:40 GMT
Set-Cookie: lang_select_language=en; Expires=Sun, 21-Aug-2016 20:24:42 GMT; Path=/
* 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',
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.