HTTP status code 4xx vs 5xx

It is totally upto you that what response you want to send to client.

But while sending a response you must be aware that it should be generic and clear about the incident which caused the request to fail.

Designing API is like desiging an agreement between the client and server. Server has to serve to client until that agreement or API specification is followed. It should clearly indicate in Api specification docs.

In your above case since server was accepting certain values with the request param and client did not sent it, it was fault of client since client did not agreed to api specification provided ahead of sending request.

In this case server should return HttpResponseStatus.BAD_REQUEST which is equal to 400 in code.

Tip: I would suggest you should not just return error code but also provide some error message with the response if any error occurs.

e.g

response : { errorCode:4xx, errorMessage:"Some thing went wrong"}

Stick to the standards!

The decision of which HTTP status code you will send to the client is up to you but you really should stick to the standards. The RFC 7231 is the current reference for content and semantics of the HTTP/1.1 protocol. It's a must read when creating an API on the top of the HTTP protocol.

4xx vs 5xx status codes

Use 4xx status codes for client errors and 5xx status codes for server errors:

6.5. Client Error 4xx

The 4xx (Client Error) class of status code indicates that the client seems to have erred. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents SHOULD display any included representation to the user.

6.6. Server Error 5xx

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. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. A user agent SHOULD display any included representation to the user. These response codes are applicable to any request method.

Which status code you should use

For the situation you mentioned in your question, you could use 400 or maybe 422 (from WebDAV, a HTTP extension):

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

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.

Along with the status code, ensure you send a representation (such as JSON or XML) containing an explanation of the error situation in the response payload. Have a look at the RFC 7807, it describes a stardard for problem details for HTTP APIs.

A great decision chart

For more details, check this decision chart from Racksburg:

The status codes are grouped into three rough categories:

Start here:

Choosing 2xx and 3xx status codes:

Choosing 4xx status codes:

Choosing 5xx status codes: