13

I'm implementing a 'testing mode' with my website which will forbid access to certain pages while they are undergoing construction, making them only accessible to administrators for private testing. I was planning on using the 401 status code, since the page does exist but they are not allowed to use it, and they may or may not be authenticated, yet only certain users (basically me) would still be allowed to access the page.

The thing I'm wondering is if the text after the HTTP/1.1 401 part mattered? Does it have to be Unauthorized or can it basically be whatever you want to put after it, so long as the 401 is still appropriate for the error? I wanted to send a message such as Temporarily Unavailable to indicate that the page is normally available to all visitors, but is undergoing reconstruction and is temporarily unavailable. Should I do this or not?

animuson
  • 53,861
  • 28
  • 137
  • 147
  • 1
    You can change that text, but most users won't see it. Graphical browsers will show the HTML in the response body, not the reason code in the first line of the HTTP response header. So your change would mostly only matter when you're testing the server with something like `curl --head` or `telnet`. – Joe White Nov 12 '11 at 03:07
  • For this case I'd rather use a 503: http://stackoverflow.com/a/1701622/39321 – Svish Apr 25 '13 at 10:08
  • I had thought of 403, but 503 is actually more correct. 401 means: You might be able to access the resource if you provided the right credentials. For example, password or some security token are missing. Since a password isn't going to help, 401 is not appropriate. Google for "error 401", "error 403" and "error 503" for an explanation. – gnasher729 Feb 18 '14 at 23:19

3 Answers3

10

You may change them.

The status messages (technically called "reason phrases") are only recommendations and "MAY be changed without affecting the protocol)."

See http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1

However, you SHOULD :-) still use the codes properly and give meaningful messages. Only use a 401 if your condition is what the RFC says a 401 should be.

Ray Toal
  • 86,166
  • 18
  • 182
  • 232
  • In particular, 401 is not the right status for "temporary unavailable". – Julian Reschke Nov 12 '11 at 11:52
  • 503 Service unavailable like the shared link :-/ it's broken. – vhbazan May 07 '20 at 00:02
  • A 503 is a temporary condition, which a server returns when it is overloaded or undergoing maintenance or something. The link works fine now, by the way. You just hit that server when it was down (lucky you, hehe). But yeah, good point! If you saw the status message "Service unavailable" then that server did send you a meaningful error message. If it sent you the word "broken", however, I would argue that would not be meaningful, since "broken" covers waaaaaaaaay too many possible conditions. – Ray Toal May 07 '20 at 00:46
2

Yes, the reason phrase can be changed. It doesn't affect the meaning of the message.

But if you need to say "temporarily unavailable", you need to make it 5xx (server) code. 503 seems right here (see RFC 2616, Section 10.5.4).

Julian Reschke
  • 40,156
  • 8
  • 95
  • 98
1

You MAY change the text (very few http clients pay any attention to it), but it is better to use the most applicable response code. Afterall, indicating the reason for failure is how the various response codes were intended to be used.

Perhaps this fits:

404 Not Found The requested resource could not be found but may be available again in the future.[2] Subsequent requests by the client are permissible.

Raymond Hettinger
  • 216,523
  • 63
  • 388
  • 485
  • I thought about 403 at first, but authentication will solve the problem in the case of administrators as well as its only temporary, where the 403 status specified that `the request SHOULD NOT be repeated`. I feel that implies that it should never be repeated. No? – animuson Nov 12 '11 at 03:10
  • Then you should go with: 404 Not Found The requested resource could not be found but may be available again in the future.[2] Subsequent requests by the client are permissible. – Raymond Hettinger Nov 12 '11 at 03:57