Putting detailed REST error message in HTTP Warning header, good/bad idea?

user_752918 0
Viewed 14229

We are developing a standard REST service using HTTP status codes as its response code if something went wrong. (e.g. invalid user input would return "400 Bad Request" to the client)

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

We would like to be as faithful to the HTTP specs as possible, so after studying the specification in the RFC2616, we are thinking of putting the detailed error message in the HTTP Headers, specifically on the HTTP header warning field. It said on the RFC that:

The Warning general-header field is used to carry additional information about the status or transformation of a message which might not be reflected in the message. This information is typically used to warn about a possible lack of semantic transparency from caching operations or transformations applied to the entity body of the message.

There seems to be no restriction on using this header for other warnings (such as REST error message), even those that are unrelated with the cache warnings as per the original intention of this header. We like the semantic, and we planned to use the 299 warning code, which seems to fit the bill quite nicely:

299 Miscellaneous persistent warning The warning text MAY include arbitrary information to be presented to a human user, or logged. A system receiving this warning MUST NOT take any automated action.

So, given the invalid input error case presented on the top of this question, we're thinking of putting our REST error message like 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 detailed this message in X-Warning header, but this seems to be not standard. We are wondering what would the hive wisdom of stackoverflow REST crowd think about this. Is there also any better/standardized practice for passing out detailed error messaging in REST responses?

response rest http-headers
7 Answers

I'm in favor of using headers for warning only when the request succeeds in general.

For example a service that get's a user's details, but some of the details come from a third party which often goes down. In our case it was appropriate to leave that section of the user data blank, but show a warning to the user that some data is missing.

So the request returned a 200 Success with a payload that contained everything we could retrieve, but then had warning headers that described the error for the rest.

user_8250770

The Warning HTTP header is likely to be deprecated in 2022 due to lack of client support.

(It could always be reactivated or repurposed in the future, though, so I would be quite wary about changing the semantics outside of a closed ecosystem.)

There appears to be a standards-track “Proposed Standard” RFC purpose-made for this sort of thing:

Although it hasn’t been updated since early 2021, there is also draft-cedik-http-warning - Communicating Warning Information in HTTP APIs under discussion on GitHub.

user_57119860
Related