Putting a detailed REST error message in the HTTP warning header is a good / bad idea?

Question

We are developing a standard REST service using HTTP status codes as the response code if something went wrong. (for example, an incorrect user input will return a "400 Bad Request" to the client)

However, we felt that a more detailed error message would be useful to the client. (for example, an invalid input error is due to the fact that X is an unrecognized parameter name)

We would like to be as precise as possible for the HTTP specifications, therefore, having studied the specification in RFC2616 , we are thinking about putting a detailed error in the HTTP headers, in particular in the HTTP header warning field. He told the RFC that:

The general Warning header field is used to carry additional information about the status or conversion of a message that may not appear in the message . This information is usually used to warn of the possible absence of semantic transparency from caching operations or transformations applied to the message body.

There seems to be no restriction on the use of this header for other warnings (such as a REST error message), even those not related to cache warnings in accordance with the original intent of this header. We like the semantics, and we planned to use the warning code 299, which seems to fit the bill pretty well:

299 Other constant warning. The warning text MAY include arbitrary information that must be presented to the user or registered . The system receiving this warning SHOULD NOT take any automatic action.

So, given the incorrect input of the error presented at the top of this question, we are thinking about putting our REST error message, as in the following example:

HTTP/1.1 400 Bad Request Warning: 299 ServiceName "Invalid input error: X is unrecognized parameter name." 

Is this a good idea / practice? We also found that some services describe this message in detail in the X-Warning header, but this seems not standard. We wonder what will think about it. Is there also a more efficient / standardized practice for sending detailed error messages in REST responses?

Answer 1

Why not just change the phrase reasons? This is what it is for. The text "Bad request" is standard. If you want to include additional information, use the response body. The HTTP specification says that you MUST include a response body with error details.

---

UPDATE

Based on a later reading of RFC 7231 and related materials, it seems the only good reason for changing the reason phrase is to localize the text rather than provide a more specific meaning. Sorry.

Answer 2

When you submit your feedback, whether in the body of the message (content) or in the header of the warning, be careful not to provide any information that may be useful to an attacker performing penetration testing on your system.

Sometimes less information is better.

Answer 3

I am a supporter of the general approach. We should assume that the client developer is in a different team from the service developer, maybe in a different time zone, etc. Perhaps even another company. It is not good to return the answer “no, that a bad request”, as the client can solve the problem.

So philosophically: tell the client what they can fix. Errors that are purely a server area (for example, a connection error to the database or some kind of logical problem), it’s fair to just return the 500 error. And here I will not send any details, we do not want to disclose information about our internal implementation to the client .

So far, I have been returning data to the response body using JAX / RS:

 return Response.status(400).entity("some message here").build(); 

I think using headers might be cleaner.

Answer 4

If this is an offer , it is an alternative to send detailed error messages. [ http://tools.ietf.org/html/draft-nottingham-http-browser-hints ]

Despite the fact that this is an ID, it is quite stable lately, and I see no problems with creating my own implementation. (I did.)

Answer 5

429 Too many requests (RFC 6585) The user has sent too many requests in a given amount of time. Designed for use with speed limiting circuits.

Since you allow one request per lifetime, you implement a rate limiting scheme, so this is the appropriate HTTP response.

You can also (and are encouraged by the HTTP specification) to customize the body of the HTTP response, so you can change "Too many requests" to whatever explanation you want.