Question

Scenario:

A POST request is sent to process an order that will result in data retrieval from an external datasource.

There are three possible results:

1. The datasource returned data for the request
2. No data was available for the request (this is viewed as an error)
3. The datasource couldn’t be accessed (may be down for maintenance)

An obvious response for 1 is 200: OK or 201: Created (an entity is created from this request).

What status codes would be appropriate for 2 and 3?

Status codes I have considered:

• 503: Service Unavailable when datasource is down
• 500: Internal Server Error when datasource is down
• 502: Bad Gateway when “no data available”
• 404: Not Found when “no data available”
• 403: Forbidden when “no data available”
• 412: Precondition Failed when “no data available”

Answer 1

2) Looking back at this, I agree it should probably be either a 204 No Content or maybe a 200 with a body indicating no records or resources could be found depending on the structure returned.
404’s are generally used when the resource URI doesn’t exist or a resource in the URI is not found in the case of a restful service.

3) 503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.

  Note: The existence of the 503 status code does not imply that a
  server must use it when becoming overloaded. Some servers may wish
  to simply refuse the connection.