Can we create custom HTTP Status codes?

Question

I have a REST and WCF service and want to send a custom status code based on the operation.

For example when some validation fails then I want to send HTTP 444 and when authorization fails I want to send HTTP 455

The question is how do we have it validated for both SOAP and REST web services.

On the client how does the error code act because when you send an HTTP 400/500 from a WCF Service (using SOAP) an exception is thrown on the client showing the status code?

Now if I send a new custom status code how does the client handle this?

Hannover

Is this a service you're exposing to the world, or do you control all the clients too? – Minier

Answer 1

Yes, as long as you respect the class -- that is, 2xx for success, 4xx for Client error, etc. So you can return custom 4XX error codes (preferably those that are unassigned) for your own application's error conditions.

To quote from [RFC 2616][1]:

"HTTP status codes are extensible. HTTP applications are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, applications MUST understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class, with the exception that an unrecognized response MUST NOT be cached. For example, if an unrecognized status code of 431 is received by the client, it can safely assume that there was something wrong with its request and treat the response as if it had received a 400 status code."

Class'

• 1xx: Informational - Request received, continuing process

• 2xx: Success - The action was successfully received, understood, and accepted

• 3xx: Redirection - Further action must be taken in order to complete the request

• 4xx: Client Error - The request contains bad syntax or cannot be fulfilled

• 5xx: Server Error - The server failed to fulfill an apparently valid request [1]:

https://www.rfc-editor.org/rfc/rfc2616#section-6.1.1

Boehm

Don't use unregistered status codes, except for testing. – Gigantopithecus

(Sorry, got cut off by 5 minute comment-edit rule...) We use custom status codes on the server side (unassigned by the RFC, with an appropriate class prefix) to differentialy process AJAX requests in JavaScript. The above quoted RFC seems to clearly state this is okay, but if it's bad practice, it would be good to understand why? – Boehm

ChrisNY: well, if you rely on unregistered status codes in your use of HTTP, there may be breakage if somebody else uses the same code for a different purpose. If you need more detailed error information you can still embed it in the payload (see for instance tools.ietf.org/html/draft-nottingham-http-problem-06) – Gigantopithecus

@ChrisNY: Most web applications are designed to work with a single client (your javascript/ajax code) and a single server (your server) so using a custom status code is completely fine. In these situations, it isn't even possible for 'somebody else' to cause 'breakage' by using the same status code. – Bookman

That quote isn't saying you can make up your own codes, it's saying your app doesn't need to know what every registered code is as long as it respects the code class and throw an error for a 4xx etc. With that aside, the only issue I could see is that in the future, one of these codes gets officially assigned and browser/javascript functionality might change. e.g. 494 DDNS attack stop all communication, browser might see that and block js from initiating any more comms to that ip. Highly unlikely but you can't be 100%, Twitter seem to think it's ok to do 420 Enhance Your Calm – Haematoblast

The spec is saying you can make up your own codes, and uses the code 471 as an example. It says to assume any unrecognized 4xx error as equivalent to 400. – Fallonfallout

Laravel generates "419" "if the authentication token is missing". Nginx generates "499" if "client closed the connection before the server answered the request". Logs are interesting. – Pattern

@Bookman Using that logic there's no reason to use HTTP at all. Use whatever message format fits your needs. Why bother satisfying some external standard if your server will only communicate with your frontend? – Yellowthroat

@JuanPerez Inventing your own protocol and supporting code would be a huge waste of time. There is nothing in the HTTP spec that says you can't use custom status code as pointed out in the answer that we are commenting on. – Bookman

Answer 2

I recommend against creating your own HTTP status codes, when applicable codes already exist for the things that you want to do in your example.

• Unprocessable failure: Status 422
• Authorization failure: Status 403

From https://www.rfc-editor.org/rfc/rfc4918#section-11.2:

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.

It can be argued that "unable to process" could be due to a validation error.

Gigantopithecus

Authorization failure is 401, not 403. 403 is forbidden, where authorisation would not fix the problem. – Oneiromancy

401 is about failed authentication (despite the name). – Gigantopithecus

401 is "Please login (again)" – Matelda

Can I ask why you recommend not to create our own custom codes? What would be the disadvantage of not following the convention? – Yellowthroat

Because the introduction of new codes requires coordination, unless you don't care about potential collisions. – Gigantopithecus

Answer 3

Here's the full list of all the available/unavailable HTTP codes.

https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

For example, the following arrowed ones are available to use (because they are unassigned) on 4XX family.

Involve

Answer 4

Yes you can add custom error codes. If possible use codes that already exist though, and if you are declaring new ones be careful to avoid collisions.

You should be aware though that some proxies filter unknown codes. I had issues with users that where behind proxies that mapped 5XX to 500, and 4XX to 404. This made my ajax calls that where checking the status code to fail.

Reconstructionist

yes, proxies suck. I don't know the proxy implementation name, but it interpreted a custom status code of ours on its own and didn't send the response to the client. – Kalakalaazar

Answer 5

Some applications add their custom response codes in the range 600-799. Check for example the response code list from KeyNote here

Keynote Defined Error Codes (600-799)

600: CONNECTION ERROR - This indicates a general connection error
601: INCOMPLETE ERROR - This indicates sever sends an incomplete page/object (as indicated by Content-Length header)
602: UNEXPECTED CLOSE ERROR - This indicates socket connection has been closed unexpectedly
603: REFUSED ERROR - This indicates a request to connect to the server is refused
604: TIMEOUT ERROR - This indicates there is no activity in socket connection in 3 minutes
605: REDIRECT ERROR - This indicates an error in redirect HTTP header
606: SSL ERROR - This indicates a general error in SSL
607: HEADER ERROR - This indicates a malformed HTTP header
608: EMPTY RESPONSE ERROR - This indicates server doesn't send any response after a request is sent
609: UNKNOWN HOST ERROR - This indicates socket receives an unknown host error from DNS
610: NO ROUTE TO HOST ERROR - This indicates a no route to host error was received while attempting to open a socket
611: SOCKET ERROR - This indicates a general socket error
612: FRAME LOOP ERROR - This indicates a page has a frame loop (frame A includes Frame B that includes Frame A)
613: REDIRECT LOOP ERROR - This indicates a page has a redirect loop (page A redirects to page B that redirects to page A)
614: CONNECTION RESET ERROR - This indicates socket receive a reset signal from the server
615: SOCKET PROTOCOL ERROR - This indicates an error in socket protocol
616: SOCKET BIND ERROR - This indicates an error in binding the socket
617: CONNECTION ERROR - This indicates a general socket connection error
618: CHUNK ERROR - This indicates an error in chunked encoding
619: SSL TIMEOUT - This indicates a timeout during SSL handshake (2 minutes)
620: SSL END OF INPUT - This indicates an end-of-file is received during SSL handshake
621: SSL HANDSHAKE ERROR - This indicates a general error during SSL handshake
622: SSL CERTIFICATE ERROR - This indicates an error in SSL certificate verification
623: SSL AUTHENTICATION ERROR - This indicates an authentication error during SSL handshake
624: SSL BAD MAC ERROR - This indicates a bad MAC during SSL handshake
625: SSL CIPHER ERROR - This indicates a cipher error during SSL handshake
701: ERROR TEXT FOUND - This code is returned if any error text (such as, "Service Unavailable") are found in the main page (frame HTML contents included). Note that the error text must be defined in advance of the test. Error text means if the text is found, this session should be considered a failure.
702: REQUIRED TEXT NOT FOUND - This code is returned If not all required texts are found in the main page. Note that required text must be defined in advance of the test. Required text means if the text is not found, this session should be considered a failure.
703: HTML BODY EMPTY - This code is returned if the HTML body of the page is empty (only if error text or required text has been defined).

Whether this is good practice I would not dare to say, but it is an interesting reference at least.

Clairclairaudience

Those values are illegal, in that the HTTP spec does not allow anything outside 100...599. – Gigantopithecus

@JulianReschke I even mentioned that I "don't dare to say whether it is good practice". I merely add a reference to what other applications do. Down voting my answer because Keynote uses illegal status codes seems unjustified. I am only feeding the discussion. – Clairclairaudience

Answer 6

No, you can only use rfc documentation requirements code, see details in RFC1945

Boorish

You can use any status code defined in iana.org/assignments/http-status-codes. – Gigantopithecus

@Julian, does this mean Rajesh can use the "427-499 Unassigned" ones for his purposes? – Citation

OK then :-) You can use any assigned status code from that list. Or you an write a specification for a new status code and get it registered. – Gigantopithecus

You can, technically, use whatever you please to yous. Just don't expect it to play well with anyone else. As asked in the OP -- if Rajesh controls all clients he can make them understand "1337 - All your base are belong to us" it they so pleases. ;) – Franks

You linked to HTTP/1.0 status codes, which has not been used since the early 90ies. – Sisterinlaw