title: 3rd party API gives back 500 error, what code should my API return
body: <p>I've written an API in a framework based on ZF2 (Zend Framework 2) called Apigility.</p>
  
  <p>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.</p>
  
  <p><strong>How should MY API respond back to my client?</strong></p>
  
  <p>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.</p>
  
  <p>Update: below is what i'm seeing from the third party.</p>
  
  <p>I think I like the idea of <code>503 Service unavailable</code>.. with an error message cluing the user into what's wrong, and how to fix it.</p>
  
  <p>Update showing 3rd party's response :</p>
  
  <pre><code>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
  </code></pre>
  
  <p>Thoughts?</p>
  
  <pre><code>/**
   * Status titles for common problems
   *
   * @var array
   */
  protected $problemStatusTitles = array(
      // CLIENT ERROR
      400 =&gt; 'Bad Request',
      401 =&gt; 'Unauthorized',
      402 =&gt; 'Payment Required',
      403 =&gt; 'Forbidden',
      404 =&gt; 'Not Found',
      405 =&gt; 'Method Not Allowed',
      406 =&gt; 'Not Acceptable',
      407 =&gt; 'Proxy Authentication Required',
      408 =&gt; 'Request Time-out',
      409 =&gt; 'Conflict',
      410 =&gt; 'Gone',
      411 =&gt; 'Length Required',
      412 =&gt; 'Precondition Failed',
      413 =&gt; 'Request Entity Too Large',
      414 =&gt; 'Request-URI Too Large',
      415 =&gt; 'Unsupported Media Type',
      416 =&gt; 'Requested range not satisfiable',
      417 =&gt; 'Expectation Failed',
      418 =&gt; 'I\'m a teapot',
      422 =&gt; 'Unprocessable Entity',
      423 =&gt; 'Locked',
      424 =&gt; 'Failed Dependency',
      425 =&gt; 'Unordered Collection',
      426 =&gt; 'Upgrade Required',
      428 =&gt; 'Precondition Required',
      429 =&gt; 'Too Many Requests',
      431 =&gt; 'Request Header Fields Too Large',
      // SERVER ERROR
      500 =&gt; 'Internal Server Error',
      501 =&gt; 'Not Implemented',
      502 =&gt; 'Bad Gateway',
      503 =&gt; 'Service Unavailable',
      504 =&gt; 'Gateway Time-out',
      505 =&gt; 'HTTP Version not supported',
      506 =&gt; 'Variant Also Negotiates',
      507 =&gt; 'Insufficient Storage',
      508 =&gt; 'Loop Detected',
      511 =&gt; 'Network Authentication Required',
  );
  </code></pre>