A Poll: Web Api Calls

A couple of days ago I threw out a poll on twitter to see what people thought of a particular question I had in mind. Here it is:

What I’m after is pretty simple … how should one handle exceptional cases in Web Api development. Namily JSON and XML. My take on it is pretty simple. If I have an API call that is a HTTP GET for the following URL: http://example.org/api/v1/users/get_orders.json

I feel I should get a list of orders back.

What if there are no orders to return (maybe this is a new account, maybe the person who owns this account deleted them all, etc)? I feel I should get back an empty list of orders. However, some API’s on the web (that shall remain nameless at this time) return this scenario as a “error document”. The problem with this is that an “error document” should be used for errors and exceptions, not known and valid use cases.

Example: if I’m required to pass in my API KEY through the HTTP Headers and I give your API an invalid key, then I would expect that you return an error document back to the caller (my client app). That is an error! An empty list of orders is a valid use case.

Let my client app decide what I should do, I’m consuming your data, you’re not consuming my application.

What’s your opinion? (Please vote as well, thanks!)