CODEWITHSUNDEEP
resthttp-status-codeslaminas-api-tools
Erik
Erik

Reputation: 3198

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

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

Upvotes: 49

Views: 26852

Answers (5)

David Ferenczy Rogožan
David Ferenczy Rogožan

Reputation: 25411

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.

Upvotes: 40

Gili
Gili

Reputation: 90023

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.

Upvotes: 0

Guillaume Cisco
Guillaume Cisco

Reputation: 2945

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.

Upvotes: 0

ccov77
ccov77

Reputation: 791

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).

Upvotes: 7

Vlad
Vlad

Reputation: 1763

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.

Upvotes: 8

Related Questions