Which status code is correct 404 or 400 and when to use either of these?

Question

What is the status code should return when an object inside my resource is not available?

{
  "Id": 0,
  "name": "user1",
  "scheme": {
    "id": 15,
    "name": "scheme1"
  }
}

What should be the response code if the scheme with id 15 does not exist?400 or 404?

Answer 1

I don't think 404 is suitable for this situation if the request has been performed to a URL that points to a resource that does exist. The problem is in the payload, so 404 has nothing to do with it.

The syntax of the JSON document is valid, so 400 is not suitable either.

What you have is an unprocessable entity due to invalid data, so 422 would be the best alternative here. Keep reading for a more detailed explanation.

Not found and Bad request

Assuming that the request has been performed to a URL that locates a valid resource (that is, a resource that exists), returning 404 is not suitable for this situation and it may yield misunderstanding:

6.5.4. 404 Not Found

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent; the 410 (Gone) status code is preferred over 404 if the origin server knows, presumably through some configurable means, that the condition is likely to be permanent.

Returning 400 with a descriptive message in the payload would be suitable for this situation if the JSON was malformed, but that's not the case:

6.5.1. 400 Bad Request

The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

Unprocessable entity

As a matter of fact, what you have is an entity that cannot be processed by the server due to invalid data. So returning 422 and details about the error in the response payload would be the most suitable approach for this situation:

11.2. 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415 (Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

^{Just read JSON when it says XML.}

You also may find this answer helpful.

Problem details for HTTP APIs

HTTP status codes are sometimes not sufficient to convey enough information about an error to be helpful. The RFC 7807 defines simple JSON and XML document formats to inform the client about a problem in a HTTP API.

It also defines the application/problem+json and application/problem+xml media types.

Picking the right 4xx status code

The following diagram (extracted from this page) is pretty insightful when it comes to picking the most suitable 4xx status code. Hopefully it will help you:

Answer 2

What is the status code should return when an object inside my resource is not available?

Michael Kropat put together a pretty good flowchart for choosing an HTTP status code.

The first step is to determine whether or not you have an error at all. It's perfectly reasonable for resource schema to include optional elements. If that's appropriate for your circumstances, then just use a 200 and call it a day.

On the other hand, if it is an error, you now need to evaluate the cause of the fault.

If the problem stems from the request, then you should be looking at entries in the 4xx class of status code.

The 4xx (Client Error) class of status code indicates that the client seems to have erred.

These are all variations of a problem with the HTTP Request itself; the client shouldn't have requested that resource, or the client needed to include different information in the request, or... lots of different variations spelled out by RFC 7231.

The heuristic here is that the client can fix things by sending a different request.

On the other hand, if the request was fine, but the server can't respond correctly right now, then you should be looking at the 5xx class

The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method.

The 5xx class is much smaller; 500 is almost always the correct choice, the protocol doesn't care very much about communicating the details to the client because there's nothing the client can to address a server issue.

My best guess, from your example, is that you should either be sending a 500 response with a payload that contains "an explanation of the error situation", or you should be sending a 200 response with a payload that includes the representation of the resource, even if that representation doesn't include all of the optional elements.