A third-party API returns 500 errors, which code should my API return

Question

I wrote an API in a ZF2-based framework (Zend Framework 2) called Apigility.

My service may request third-party APIs. From time to time, I return an error message 500. either because of expired tokens, or because of some of these.

How will the MY API respond to my client?

At first I thought that I should return 500, but in fact it seems to be wrong. I do not want to return an error indicating that I crashed. This is a third party that has 500'd.

Update: below I see a third person.

It seems to me that I like the idea of 503 Service unavailable .. with an error message in which the user tries to understand what is wrong and how to fix it.

Update showing a third-party 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\'ma 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 is up to you which error code you will use. But if the actual functionality of your API depends on a third-party API, I would consider using the HTTP 503 Service Unavailable code, because your service will not be available until the third-party API works, there is no question which HTTP code is returned to the third-party API. I would also like to include some details (error message) in the response payload.

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

I would reflect HTTP codes from a third-party API for the user only if your API acts as a proxy server without any additional functions.

Answer 2

When a client calls your API, does it directly or indirectly indicate that it wants your API to interact with a third-party service?

• No - then for the client it will be 500, because it is still an internal Server Error from the point of view of the client. If your API cannot interpret the error message from a Third Party Service and get a more specific error code.

• Yes - then 503 seems most appropriate here. The error message may indicate which service is not available.