17

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.

Alexander Mills
  • 90,741
  • 139
  • 482
  • 817

3 Answers3

74

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:

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

Community
  • 1
  • 1
cassiomolin
  • 124,154
  • 35
  • 280
  • 359
1

The answer lies in the defined semantics of the other http codes. For instance, for a protected page, an authentication failure is an expected error, so the 401 is an appropriate response. One could even argue that 401 is a legal response, not even an error code, four that situation. And that distinction may be the semantic reason that it is probably ambiguous to decide whether an expected error code is actually an error or just legal result of the request.

miw
  • 776
  • 4
  • 11
-1

In many cases, returning a 200 and having a custom domain specific status/errorcode/reason is probably better.

Like you said, returning 500 generally signals that the server could not complete executing the request. I'd like to view a 500 basically as equivalent to the server crashing or throwing an exception, and I would avoid throwing it for any kind of error that can be predicted and handled gracefully.

If what you're looking for is more something like "server could indeed evaluate the request but found that what the user asked for cannot be accomplished for some reason" (for example some resource is depleted) then you're probably better off with a 200 + custom status code, unless the reason matches one of the specific codes in the 4xx range (e.g. a 403 for "user does not have the needed privileges").

JHH
  • 8,567
  • 8
  • 47
  • 91