Making additional error information available to clients is not a big ask. Sure, sometimes it is impossible for the server to supply that info (e.g. the server doesn’t get the request, intermediary strips it out, the server dies) and sometimes the client will ignore the response (e.g. client doesn’t recognize the format, client dies, etc.). But these are exception cases that are handled in the normal course of things. HTTP is, by design, an unreliable protocol.

I used the word “should” (not “must”) and, if it makes folks feel better, I’d be happy to adjust that to “Whenever reasonably possible servers should…” as it doesn’t change the state of affairs at all.

Now, I will grant you some Web frameworks make it hard for developers to inject meaningful content into error response bodies, but that’s a matter for the framework folks, not the protocol.

Finally, as William already pointed out, using a Link , rel=”error” is a fine way to sidestep lots of payload issues and still provide clients additional helpful information.

Interestingly, soon after Mike posted his comment he and I had a little back-and-forth on Twitter that was along the same lines as your comment. See: me, him, me, him.

As you can see, his solution to the unclear/unsuitable media type is to use a link header w/ rel=”error”.

That’s a big ask. If you’ve got a web-server passing a request to an app-server, and the app-server dies, then how can the web-server have any idea what format that URL call is expected to return.

What if the web service offers a response in either XML or JSON, depending on a parameter, and the client specifies an invalid parameter.

And that’s assuming the client request even makes it to the requested web-server. What about the network being down at the client end.

I would say that, as a client calling a web service, you need to first cater for all the HTTP errors, and then a generic “does the response conform to an expected format”, and then any specified error response structure.

The error message body is an important _addition_ to the HTTP response code and can carry any interesting data API designers consider important including a link to another resource that can carry even more details (whether a generic help message or details real-time logging data).

In a recent blog post (http://amundsen.com/blog/archives/1054) I discussed a generic version of an error message that can be easily adapted to any media-type.

This same approach is covered in better detail in the “RESTful Web Services Cookbook” by Subbu Allamaraju.

Reading your comment, I remembered the Cloud Tools Manifesto that you wrote a while ago and which contains much of what I describe here. I am pretty sure a lot of my thinking on this traces back to when I read that entry on your blog, and the practical confirmations I’ve seen since.

0. Service APIs must provide some machine parseable response. Soap faults aren’t that bad a design to start from.

1. Service APIs must document all known errors, with parseable examples.

2. Mock service endpoints should be provided to simulate failures like asking for some machines and getting you card declined, or asking for 500 machines and getting back 12.

There’s some interesting politics here, because failure mode handling becomes the barrier to moving between apparently identical API implementations; just because Eucalyptus implements the EC2 API doesn’t mean it fails in the same way.