HTTP status code for "could not fulfill request for *known* reason"

HTTP 500 means the server could not fulfill the request for an unexpected reason. What is the best HTTP response code to use when the server could not fulfill the request for a reason that is known or expected?

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

looking through some docs on HTTP, I can't find a good answer and it seems to be an important distinction. Throwing up a 500 for an error that doesn't really represent an "internal server error" is probably not a good practice.

What is a 402 HTTP error?

The HTTP 402 Payment Required is a nonstandard response status code that is reserved for future use. This status code was created to enable digital cash or (micro) payment systems and would indicate that the requested content is not available until the client makes a payment.

What is HTTP status code 1xx?

A 1xx Informational status code means that the server has received the request and is continuing the process. A 1xx status code is purely temporary and is given while the request processing continues. For most tasks you won't encounter these much, as it's not the final response to the request. 100 Continue.

What does the HTTP status code 401 indicate?

The HyperText Transfer Protocol (HTTP) 401 Unauthorized response status code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.

What is status code 204 no content?

5 204 No Content. The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. The response MAY include new or updated metainformation in the form of entity-headers, which if present SHOULD be associated with the requested variant.

Don't use the RCF 2616 as reference anymore

The RFC 2616 is no longer relevant nowadays and anyone using such document as reference should stop right away. Quoting Mark Nottingham who, at the time of writing, co-chairs the IETF HTTP and QUIC Working Groups:

Don’t use RFC2616. Delete it from your hard drives, bookmarks, and burn (or responsibly recycle) any copies that are printed out.

The old RFC 2616 has been supplanted by the following documents that, together, define the HTTP/1.1 protocol:

RFC 7230: Message Syntax and Routing
RFC 7231: Semantics and Content
RFC 7232: Conditional Requests
RFC 7233: Range Requests
RFC 7234: Caching
RFC 7235: Authentication

If you are looking for status code definitions, then the RFC 7231 is the document you should refer to.

What's the known or expected reason?

Depending on the known or expected reason, you can return the proper status code:

Couldn't the request be fulfilled because the client is requesting a resource that does not exist? Return a 404.
Is it an authorization problem? Go for 403.
Using HTTP authentication and the credentials are not valid? Return a 401.
Doesn't the server support the functionality required to fulfil the request? Use 501.
Couldn't the request be completed due to a conflict with the current state of the target resource? So 409 should be returned.
Has the target resource been assigned a new permanent URI? The 301 status code is the right choice.
And so on...

Decision charts

For more details, check the RFC 7231 and also have a look at the following decision chart that Michael Kropat put together:

The status codes are grouped into three rough categories:

HTTP status codes categories

Start here:

HTTP status codes

Choosing `2xx` and `3xx` status codes

HTTP 2xx and 3xx status codes

Choosing `4xx` status codes

HTTP 4xx status codes

Choosing `5xx` status codes

HTTP 5xx status codes

HTTP status code for "could not fulfill request for known reason"

Tags:

http

server

web

Alexander Mills

People also ask

1 Answers