Exception payload / error handling

[Jørn Wildt]

How are you guys returning error information in your APIs?

I am building a more or less traditional HTTP API - you can GET stuff, modify through POST/PUT and so on. Nothing really fancy there. Now I am trying to improve the error responses to help clients and client programmers with error handling and debugging.

The API is of course using the normal HTTP error codes, but how should more detailed information be returned?

Here is a couple of scenarios:

1) The client asks for a JSON representation of, say, a sales order. Unfortunately the specified sales order ID is in the wrong format so the server returns 400 Bad request (meaning the client must change its request before trying again).

2) The client POSTs an update of a sales order. Unfortunately it forgot to include a mandatory parameter so the server returns 400 Bad request.

3) The database makes a timeout and the server returns 500 Internal server error (meaning the client can try the same request again).

4) The server hits a bug and returns 500 Internal server error.

How can the server tell the client *why* the error occurred and what the client can do to fix it?

- Should it return a JSON object with some "well known" error format representation?

- Is it better to simply return text/plain with a description of the error? Or text/html?

- What if the client asks for application/xml - should it then get application/xml with an error representation?

- What if the client asks for a custom media type - should that media type include a standard way of encoding errors?

- Would it be beneficial to invent a custom error media type?

In general - should the error be represented in the same format as the client asked for?

Thanks, Jørn

[James McGinty]

Hi Jorn, in our case, we return an "Error message" media type along with the appropriate HTTP response code.
So if we return a 400-499 or 500-599 error, we have a standard error type which has fields like "error code" "message" etc.
All exceptions & user errors return the same structure, which should be easy to deal with from the client end.

James

[Jørn Wildt]

Thanks!

Is that media type negotiated by the client? Meaning; does the client include that media type in it's "Accept" header? Is your media type based on JSON, XML or something else? Do you have a specific "standard" client in mind (for instance a dedicated mobile client)? What if the client did not specify you media type in it's "Accept" header - what would you then do?

I am asking since I would expect different types of clients to handle one format better than another. For instance, I don't expect mobile clients to be good at parsing XML - they would prefer JSON (I am not an expect in this field, so I may be wrong). Whereas enterprise mashup/integration clients might prefer XML.

I do like the idea of a dedicated error media type, but the server must have some kind of appropriate fallback handling if the media type is unsupported by the client.

On the other hand - if the client only asks for a very specific custom media type that does not have error semantics, how should the server then react?

Thanks, Jørn

[mca]

I take the follow approach to "reporting errors" in Web APIs:

1) When I am designing the media type, I include an "error" block[1][2] that MAY appear when the server encounters an error.

2) When using an existing media type (i.e. HTML), I usually declare an identifier (i.e. @class) to mark off an "error" block.

<div class="error">

  <p class="title" />

  <p class="code" />

  <a class="error" href="..." />

</div>

3) In a few cases, I've used a Link header[3] w/ a link relation (rel="error" or rel="http:///error") that is sent w/ the HTTP error. This allows the client to retrieve additional data and, if needed negotiate for the format of the response representation.

[1]  http://amundsen.com/media-types/collection/format/#objects-error 

[2]  http://amundsen.com/media-types/maze/format/#error-element 

[3]  http://tools.ietf.org/html/rfc5988 

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[sune jakobsson]

In OMA we have defined how the server should behave in cases where the client comes with something it does not understand. It is descriped in the REST API whitepaper.

Sune

[Daniel Roop]

My approach is similar to mca's.

We have defined a error content type that can be included or returned stand alone.  In JSON it typically looks like this

"errors" : [

   {

       "typeId" : <<JSON-String>>,

       "message" : <<JSON-STring>>

   },

   ....

]

We then allow the client to program against the typeId.  We alos allow additional properties to be returned on occasion for specific typeIds, that the client may or may not know/care about.

For instance

{

    "typeId" : "INVALID_LENGTH",

    "message" : "The name property can only be 25 characters long"

    "maxLength" : 25,

    "field" : "name"

}

In this case field represents a json property locator for the field that failed (based on the location of the error object) and maxLength is meta data so the client can leverage provide custom messaging if they chose not to use the standard that the server provides.

We started assuming this would be it's own content-type that got returned, as a first class citizen, but have realized there are needs for "partial-success" where you might want to say this part worked, but this didn't (I know not an ideal state, but still a valid state some time when you are trying to be resilient or backend systems won't cooperate).

To your question about what do we expect the client to send in the Accept.  We assume this is part of our standard content type, but it is also json. So if the client sent Accept: application/json or Accept: application/vnd.roopsays+json;type=Error or Accept: application/vnd.roopsays.ApiContentType+json  we would return the response.  I would imagine this could work with the xml version of these content types as well. The main point being if your client says they accept json/xml it is still valid to return them something that has more context, as long as it is json/xml even if they didn't ask for it.

Daniel

[Jeff Schmidt]

Our service relies heavily on JSONP, and HTTP status codes are not
available to the client-side JavaScript. It's important to actually
make sure a response is returned so the client-side callback function
is invoked (even for 500 server error), rather than just time out. The
response then must indicate success or failure, and in the case of
failure, provide some indication as to what the failure(s) entails.

Jeff

> <sune.jakobs...@gmail.com>wrote:

> >>> On Tue, May 29, 2012 at 12:19 PM, James McGinty <james.mcgi...@gmail.com

[Arlo Belshee]

Also consider in your error design whether you want to support server-side response streaming. If you do, there will be errors that happen after you have already sent the status code, all headers, and some random amount of the body.

So you'll need a way to say "oh, that success error code? Sorry; I lied. Here's what I should have said." And you need to decide how to handle the fact that you have emitted the first n arbitrary chars of your response, so the doc is not in a valid XML / Json state when you find the error.

Arlo

Sent from my Windows Phone

---

From: Jeff Schmidt
Sent: 5/29/2012 8:16 AM
To: API Craft
Subject: Re: Exception payload / error handling

[Peter Williams]

On Tue, May 29, 2012 at 2:41 AM, Jørn Wildt <j...@fjeldgruppen.dk> wrote:
> How are you guys returning error information in your APIs?
>

> The API is of course using the normal HTTP error codes, but how should more
> detailed information be returned?
>

> - Is it better to simply return text/plain with a description of the error?

This is the approach i usually take.

Most of the automatically recoverable non-success scenarios are
covered by the standard HTTP response codes (unauthorized, for
example). In my experience it is unlikely that in other failure
scenarios an API client will be able to do anything other than just
record the failure for the humans to look at. When this is true a
simple prose description of the error is almost certainly the optimal
response. It provides exactly the information needed and fits well in
to the most common error recording and notifications systems (read:
log files and email).

In a situation where there is a chance the client could recover
independently -- and no HTTP status code covers the scenario -- it
would make sense to provide an appropriate set of link headers or
possibly a more complex, machine readable response body. However, such
situations are vanishingly rare in practice.

Peter
barelyenough.org

[Jørn Wildt]

It seems like the "general guidelines" are:

• If using a custom media type: you can (should?) design error handling into the media type itself [Mike].
• If using a standard media type like plain XML, JSON or (X)HTML: find a way to encode error messages.
  
• Make sure its straight forward to locate it - using specific XML elements/namespaces, certain JSON properties or certain HTML classes/identifiers.
• The client should know that it needs to look for the error information since it got 4xx or 5xx. Thus it wont suddenly try to decode an error response as, for instance, a sales order.
  
• No one seems to implement a specific media type for error information.
• That makes somewhat sense to me; the client would have to include that media type in the "Accept" header in each and every request it makes. That would not be unreasonable but slightly odd since I assume most clients (and devs) are used to depend on one single media type.
  

Then we have the more esoteric advices:

• The client may not be able to access to returned status code, so make sure it is possible to detect error conditions by looking at the payload alone.
  
• Allow partial errors: error codes may be part of an otherwise successful response (sounds more like a warning to me?).
• If streaming content: consider what happens if errors need to be embedded inside the data stream.

Thanks!

/Jørn

[Mike Schinkel]

On May 29, 2012, at 4:29 PM, Jørn Wildt wrote:

It seems like the "general guidelines" are:

• If using a custom media type: you can (should?) design error handling into the media type itself [Mike].
• If using a standard media type like plain XML, JSON or (X)HTML: find a way to encode error messages.
  
• Make sure its straight forward to locate it - using specific XML elements/namespaces, certain JSON properties or certain HTML classes/identifiers.
• The client should know that it needs to look for the error information since it got 4xx or 5xx. Thus it wont suddenly try to decode an error response as, for instance, a sales order.
  

What should we do for binary response types such as image/jpeg or application/pdf, or for media types where there is no reasonable way to encode an error message?

Also, what about HTTP methods for which "the server MUST NOT return a message-body in the response?" like HEAD[1]?

• No one seems to implement a specific media type for error information.
• That makes somewhat sense to me; the client would have to include that media type in the "Accept" header in each and every request it makes. That would not be unreasonable but slightly odd since I assume most clients (and devs) are used to depend on one single media type.

This was a really good catch, but it brings up a potential "double bind."  If an Accept header[2] is used and is specified to be, for example, "application/pdf" is it valid to return a message body of type "text/plain" when an error occurs?

It would seem on status codes 4xx[3] and 5xx[4] that responses "SHOULD include an entity containing an explanation of the error situation" (expect for HEAD, there's that HEAD exception again.)  Except[5] "All responses to the HEAD request method MUST NOT include a message-body, even though the presence of entity- header fields might lead one to believe they do. All 1xx (informational), 204 (no content), and 304 (not modified) responses MUST NOT include a message-body."   So how do we return error messages in those cases?  And can the entity message body differ from that which was requested via the Accept header when there is an error situation?

Then we have the more esoteric advices:

• The client may not be able to access to returned status code, so make sure it is possible to detect error conditions by looking at the payload alone.

Wasn't the mentioned use-case for this to be JSONP?  Are there other valid use-cases where status codes are not available?  

If no and given that JSONP is a hack (albeit a generally recognized and accepted hack) wouldn't that mean it shouldn't be used for general advice?

And is it okay that we have a bunch of different ways to handle error presentation, instead of one accepted way?  It doesn't sound like there is any commonality in the way people are returning errors so it seems errors will always get handled via a custom client, not via a standard client.  Basically this feels like "Error Tunneling" to me, no?

A potential way that nobody mentioned that I think would work in all cases where headers are accessible (and should be combined with appropriate HTTP status code) would be to have an "Error-Description" header?  Would this work, or if not why not?

-Mike

[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.4

[2] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1

[3] http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4

[4] http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5

[5] http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.3

[Peter Williams]

On Thu, May 31, 2012 at 6:08 AM, Mike Schinkel <mi...@newclarity.net> wrote:
> On May 29, 2012, at 4:29 PM, Jørn Wildt wrote:
>
> What should we do for binary response types such as image/jpeg or
> application/pdf, or for media types where there is no reasonable way to
> encode an error message?
>
> Also, what about HTTP methods for which "the server MUST NOT return a
> message-body in the response?" like HEAD[1]?

Well, the HTTP response status code is still workable in both
situations. My feeling is that the status code is almost always the
best way to pass error info anyway.

>> No one seems to implement a specific media type for error information.
>>
>> That makes somewhat sense to me; the client would have to include that media
>> type in the "Accept" header in each and every request it makes.
>

> This was a really good catch, but it brings up a potential "double bind."
>  If an Accept header[2] is used and is specified to be, for example,
> "application/pdf" is it valid to return a message body of type "text/plain"
> when an error occurs?

Absolutely. The accept header is not some sort of contract that the
server *must* abide by, it is information about what would be most
useful to the client. The server may respond with any media type it
sees fit regardless of what the client put in the accept header. That
means that clients should be prepared to receive responses of any
media type for any request (but they don't have to do anything
particularly useful with that responses). In an error response the
client is going to see the 4xx or 5xx status code and know that the
response is not what it wanted anyway, so the fact that body is not
the desired media type is probably entirely moot.

>> Then we have the more esoteric advices:
>>
>> The client may not be able to access to returned status code, so make sure
>> it is possible to detect error conditions by looking at the payload alone.
>
> Wasn't the mentioned use-case for this to be JSONP?  Are there other valid
> use-cases where status codes are not available?
>
> If no and given that JSONP is a hack (albeit a generally recognized and
> accepted hack) wouldn't that mean it shouldn't be used for general advice?

I agree that this should not be given as general advice. HTTP has a
response status code for the express purpose of communicating the
outcome of the request to the client. We should use it. (Of course, if
you are up kludge creek without a paddle you do whatever you have to
get the system working. But what works in that situation does not
constitute general advice.)

> And is it okay that we have a bunch of different ways to handle error
> presentation, instead of one accepted way?  It doesn't sound like there is
> any commonality in the way people are returning errors so it seems errors
> will always get handled via a custom client, not via a standard client.
>  Basically this feels like "Error Tunneling" to me, no?

I am not sure there are really a bunch of different ways to handle
errors. I think the general advice should be:

* Servers should communicate the fact that the request failed by
using the most appropriate HTTP response status code.
* Servers should use the body of the failure response to provide
commentary about the failure that might be helpful in debugging or
recovering from the failure. Such commentary should be encoded in the
media type the server thinks most useful.
* Clients should handle failure responses gracefully regardless of
the media type of the body.
* User agents should (attempt to) apply generalized HTTP failure
recovery logic if possible. (Retrying the request with an authenticate
header field after receiving an `unauthorized` response, for example.)
* User agents may (attempt to) apply media type specific logic to
recover from failure as they see fit.

That set of rules seems to cover most peoples error handling practices
(with the exception of the JSONP, which i am happy to ignore).

> A potential way that nobody mentioned that I think would work in all cases
> where headers are accessible (and should be combined with appropriate HTTP
> status code) would be to have an "Error-Description" header?  Would this
> work, or if not why not?

That is an interesting idea. What value do you see that providing over
using the status code and a plain text body?

Peter
barelyenough.org

[Mike Schinkel]

On May 31, 2012, at 10:37 AM, Peter Williams wrote:

Well, the HTTP response status code is still workable in both
situations. My feeling is that the status code is almost always the
best way to pass error info anyway.

Thanks. That was my gut feeling too.

Still, I can't help but want to explore those cases where it isn't the best way to pass error information.  Or more precisely, where status codes are not *sufficient*.

For example, let's assume I tried to access a past bank statement as "application/pdf" via the API but the bank has rules that lock down statements when the account is not in good status. A "409 Conflict" would seem to be the right response code, but it doesn't tell my why my account is not in good status; it would be preferable to be told it's because the account is overdrawn vs. the State department has frozen the account, etc. (NOT speaking from experience on the latter here. :)

So how do I pass back error description here?  I could turn the error description into "application/pdf" but then intermediaries are certain not to be able to read it, if needed.  Of course, without a standard for error descriptions that too is probably moot?

Absolutely. The accept header is not some sort of contract that the
server *must* abide by, it is information about what would be most
useful to the client. The server may respond with any media type it
sees fit regardless of what the client put in the accept header. That
means that clients should be prepared to receive responses of any
media type for any request (but they don't have to do anything
particularly useful with that responses). In an error response the
client is going to see the 4xx or 5xx status code and know that the
response is not what it wanted anyway, so the fact that body is not
the desired media type is probably entirely moot.

Again, that was my gut feeling too. But shouldn't this have been explicit in the spec? Of course that is moot too, at least until the next revision of the HTTP spec but who knows when that's likely, if ever.

It seems reasonable to send error messages via "text/plain", but it feels wrong to return "text/plain" if the header is "Accept: application/json" or "Accept: application/pdf" only.

An additional idea: Would it make sense for HTTP to (have) add(ed) an "Accept-Error" header which is like "Accept" but it instead specifies the media type expected for an error, and the default when the header is not specified would be "text/plain"? That way custom APIs could be explicit about how they expect errors to be reported and "(defacto-)standard" error message content types could potentially emerge.

I am not sure there are really a bunch of different ways to handle
errors. I think the general advice should be:

* Servers should communicate the fact that the request failed by
using the most appropriate HTTP response status code.

Check.

* Servers should use the body of the failure response to provide
commentary about the failure that might be helpful in debugging or
recovering from the failure. Such commentary should be encoded in the
media type the server thinks most useful.

Hmm.  But that's likely the best we can do at this point, at least as far as the spec is concern.

* Clients should handle failure responses gracefully regardless of
the media type of the body.

Hmm.  Not every client can be that robust; it would be impossible to anticipate every potential type even for the best clients unless you mean just give up rather than fail. Still, not the best, especially for AJAX as it might be hard to give the user an idea why things failed.

* User agents should (attempt to) apply generalized HTTP failure
recovery logic if possible. (Retrying the request with an authenticate
header field after receiving an `unauthorized` response, for example.)

Check.

* User agents may (attempt to) apply media type specific logic to
recover from failure as they see fit.

Hmm.  Workable, but could it not be better by explicitly addressing error handling?

(with the exception of the JSONP, which i am happy to ignore).

Ditto.

A potential way that nobody mentioned that I think would work in all cases

where headers are accessible (and should be combined with appropriate HTTP

status code) would be to have an "Error-Description" header?  Would this

work, or if not why not?

That is an interesting idea. What value do you see that providing over
using the status code and a plain text body?

Greater consistency.  For APIs that return content types that do not support error handling there is no current method to return an error description.  Sure we could devolve to "text/plain" but that doesn't work for partial errors, i.e. a URL that returns a list of records but for which the URL's implied query results in zero records. In this case it would be nice to have "No records found for foo=1 and bar=2" in "Error-Description."

Also, according to the HTTP spec for the Message Body[1] returning an error message in the message body would violate the spec in these cases given the "MUST NOT" wording:

"All responses to the HEAD request method MUST NOT include a message-body, even though the presence of entity- header fields might lead one to believe they do. All 1xx (informational), 204 (no content), and 304 (not modified) responses MUST NOT include a message-body."

 

So my gut tells me that "Error-Description" and "Accept-Error" headers could be used in all cases vs. just in most cases and always being able to it the same way is where I see the value. Of course this is just a straw-man proposal; feel free to poke holes into it.

-Mike

[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.3

[mca]

HTTP Status codes are meant to pass status information about HTTP, not about apps _running_ over HTTP.

In HTTP, application information (including status details) is meant to be carried in the payload itself; usually the body.

HTTP status codes are almost _never_ sufficient for carrying application-level error information.  

If passing error information is important to your application, use the payload (usually the body) for this and document it as needed, just as you do other application-level information. Using a unique media type design for each _type_ of application-level information is possible, but not recommended. Same applies to headers. 

HTTP was designed to offer archs & devs _possibilities_ in expressing app-level information, not _requirements_. For some this may be a frustration, but for most the opportunity to select the means that best suits your use case is an advantage of HTTP, not a shortcoming.

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Mike Schinkel]

On May 31, 2012, at 2:20 PM, mca wrote:

HTTP Status codes are meant to pass status information about HTTP, not about apps _running_ over HTTP.

In HTTP, application information (including status details) is meant to be carried in the payload itself; usually the body.

HTTP status codes are almost _never_ sufficient for carrying application-level error information.  

If passing error information is important to your application, use the payload (usually the body) for this and document it as needed, just as you do other application-level information. Using a unique media type design for each _type_ of application-level information is possible, but not recommended. Same applies to headers. 

HTTP was designed to offer archs & devs _possibilities_ in expressing app-level information, not _requirements_. For some this may be a frustration, but for most the opportunity to select the means that best suits your use case is an advantage of HTTP, not a shortcoming.

Understood, and this is helpful.  This is basically describing a subset of the OSI model.

But nothing you said addresses the fact that HTTP is currently ambiguous about how to pass back application errors, especially when the spec says that there MUST NOT be a message body is selected cases. The caveat in your comment "..use the payload (usually the body)..." illustrates this.

I would also disagree with what I think you implied, that error information is no different than any other application level information.  Error is one of two well-known binary states; success or failure.  It would make sense to recognize that applications may need error information out of band from content and thus providing explicit support for errors in the protocol makes sense, at least to me.

-Mike

[mca]

<snip>

But nothing you said addresses the fact that HTTP is currently ambiguous about how to pass back application errors 

</snip>

correct. is that what you want to solve/change? to make HTTP non-ambiguous on this matter?

<snip>

 It would make sense to recognize that applications may need error information out of band from content and thus providing explicit support for errors in the protocol makes sense 

</snip>

so, you agree there are multiple ways to return app-level info. you don't like that and you want HTTP to "provid[e] explicit support for [app-level] errors in the protocol" 

do i have that right?

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Mike Schinkel]

On May 31, 2012, at 2:57 PM, mca wrote:

correct. is that what you want to solve/change? to make HTTP non-ambiguous on this matter?

Yes, at least by extension.  I was hoping to explore what it would look like.

so, you agree there are multiple ways to return app-level info. you don't like that and you want HTTP to "provid[e] explicit support for [app-level] errors in the protocol" 

do i have that right?

IF I understand what you are saying, I think the answer is "yes", but specifically for errors, not at this point any other app-level info.  

And not the semantics of errors but instead a method for the protocol to provide references to the errors.  So no mixing of protocol and app, just acknowledgment in the protocol that there is a special case known as failure and that the protocol could help the app handle failures in a more expressive way.

As an aside, I think of technology as an evolution that recognizes fundamental use patterns over time. For example, the C language didn't have a foreach() but C# added it as it simplifies a fundamental usage pattern and thus now eliminates a class of related logic errors.  Recognizing that API errors exist and coming up with a good standard way to handle them via the protocol has benefits, imo.  

-Mike 

[mca]

you have interesting ideas that should be brought to the HTTPbis group.

FWIW, i'm not so interested (in this list) to talk about changing the protocol but instead how to use the existing standard to solve current problems.

regarding the subject of this thread (communicating app-level errors) i think we have uncovered more than enough options to work w/. 

 
mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Mike Schinkel]

On May 31, 2012, at 3:32 PM, mca wrote:

you have interesting ideas that should be brought to the HTTPbis group.

FWIW, i'm not so interested (in this list) to talk about changing the protocol but instead how to use the existing standard to solve current problems.

regarding the subject of this thread (communicating app-level errors) i think we have uncovered more than enough options to work w/. 

True all, with one exception: For me I only have time to actively follow a few lists, so either I talk about it here or I don't have an outlet. :)  

Also I think it's when people start trying to solve real world problems is when they actually recognize potential solutions hence why there is some value in generate to discuss on this list (although definitely not ad-nauseum; once identified it would be appropriate to take elsewhere.)

-Mike

[Peter Williams]

On Thu, May 31, 2012 at 12:20 PM, mca <m...@amundsen.com> wrote:
> HTTP Status codes are meant to pass status information about HTTP, not about
> apps _running_ over HTTP.
> In HTTP, application information (including status details) is meant to be
> carried in the payload itself; usually the body.

What? HTTP *is* an application protocol. How could it's status codes
not be about the apps?

Do you really think that the 409 conflict status code is about HTTP
and not the app "running over http"?

> HTTP status codes are almost _never_ sufficient for carrying
> application-level error information.

I disagree. I have found that most clients can't do much of anything
with information beyond what is available in the status line except
record it for consumption by a human. There probably are cases where
this is not true they are exceedingly rare edge cases and should be
dealt with as such.

> If passing error information is important to your application, use the
> payload (usually the body) for this and document it as needed, just as you
> do other application-level information. Using a unique media type design for
> each _type_ of application-level information is possible, but not
> recommended. Same applies to headers.

Agreed. If the status code is not sufficient the body is generally the
right place to put the extra info.

Peter
barelyenough.org

[mca]

On Thu, May 31, 2012 at 4:55 PM, Peter Williams <pe...@barelyenough.org> wrote:

On Thu, May 31, 2012 at 12:20 PM, mca <m...@amundsen.com> wrote:
> HTTP Status codes are meant to pass status information about HTTP, not about
> apps _running_ over HTTP.
> In HTTP, application information (including status details) is meant to be
> carried in the payload itself; usually the body.

What? HTTP *is* an application protocol. How could it's status codes
not be about the apps?

i think we've got an abstraction mis-match in our convo. HTTP is an app-layer *protocol*. when i say "app-level" i mean the _instance_ app (accounting, blogging, etc.) that is _implemented_ using a protocol (HTTP). you may use different names to differentiate the protocol from the solution implemented using that protocol.  

Do you really think that the 409 conflict status code is about HTTP
and not the app "running over http"?

In most of my apps "409" is not enough information for the user to correct the problem. it's true that in some cases the write representation sent to the server has only one possible field that could generate a conflict and it is reasonable to expect the user/dev to understand which single field that is. however, in many cases the write representations i send have more than one field that could generate a sever-side conflict and/or the user is not in a position to know which field is the culprit (inlcuding cases where the offending field is "hidden" from the user's view). YMMV 

> HTTP status codes are almost _never_ sufficient for carrying
> application-level error information.

I disagree. I have found that most clients can't do much of anything
with information beyond what is available in the status line except
record it for consumption by a human. There probably are cases where
this is not true they are exceedingly rare edge cases and should be
dealt with as such.

I get the impression that you are answering this from the POV of M2M-only work. is that correct? my answer did not make this assumption, if that helps clear up the diff in our POVs. 

[Peter Williams]

On Thu, May 31, 2012 at 12:08 PM, Mike Schinkel <mi...@newclarity.net> wrote:
> On May 31, 2012, at 10:37 AM, Peter Williams wrote:
>
>> Well, the HTTP response status code is still workable in both
>> situations. My feeling is that the status code is almost always the
>> best way to pass error info anyway.
>
>
> Thanks. That was my gut feeling too.
>
> Still, I can't help but want to explore those cases where it isn't the best
> way to pass error information.  Or more precisely, where status codes are
> not *sufficient*.
>
> For example, let's assume I tried to access a past bank statement as
> "application/pdf" via the API but the bank has rules that lock down
> statements when the account is not in good status. A "409 Conflict" would
> seem to be the right response code, but it doesn't tell my why my account is
> not in good status; it would be preferable to be told it's because the
> account is overdrawn vs. the State department has frozen the account, etc.
> (NOT speaking from experience on the latter here. :)

Well, in this situation i would prefer a prose description of why the
account is locked. If the user agent accepts HTML i would send the
error description in HTML if not i would use plain text. There is
nothing the client can do to fix the problem so burying the
description of the situation in a machine readable format just makes
understanding the problem more difficult.

> It seems reasonable to send error messages via "text/plain", but it feels
> wrong to return "text/plain" if the header is "Accept: application/json"
> or "Accept: application/pdf" only.

The real question is how are clients going to use the response. If you
are really just sending a human readable description of the error then
plain text or HTML seems most appropriate. If you are trying to convey
some information to allow the user agent to recover from the error
then you'll need a machine readable format.

> An additional idea: Would it make sense for HTTP to (have) add(ed) an
> "Accept-Error" header which is like "Accept" but it instead specifies the
> media type expected for an error, and the default when the header is not
> specified would be "text/plain"? That way custom APIs could be explicit
> about how they expect errors to be reported and "(defacto-)standard" error
> message content types could potentially emerge.

I'd be included to just put the error format in the accept header
field with a low q value.

> * Clients should handle failure responses gracefully regardless of
> the media type of the body.
>
>
> Hmm.  Not every client can be that robust; it would be impossible to
> anticipate every potential type even for the best clients unless you mean
> just give up rather than fail. Still, not the best, especially for AJAX as
> it might be hard to give the user an idea why things failed.

I disagree. If you are interacting with the user synchronously and you
get a non-success response in a media type you don't understand you
can just display and "Unknown error occurred" with a details button
that show the user the full response body. If a human is not
immediately available you can do the same thing but just shove it in
the log file.

> * User agents may (attempt to) apply media type specific logic to
> recover from failure as they see fit.
>
>
> Hmm.  Workable, but could it not be better by explicitly addressing error
> handling?

Don't see any better way to do it. Recovering from errors is
application specific so it is going to be pretty difficult to
generalize.

>>> A potential way that nobody mentioned that I think would work in all cases
>>> where headers are accessible (and should be combined with appropriate HTTP
>>> status code) would be to have an "Error-Description" header?  Would this
>>> work, or if not why not?
>>
>> That is an interesting idea. What value do you see that providing over
>> using the status code and a plain text body?
>

> Also, according to the HTTP spec for the Message Body[1] returning an error
> message in the message body would violate the spec in these cases given the
> "MUST NOT" wording:
>
> "All responses to the HEAD request method MUST NOT include a message-body,
> even though the presence of entity- header fields might lead one to believe
> they do. All 1xx (informational), 204 (no content), and 304 (not modified)
> responses MUST NOT include a message-body."

Yeah, handling an error response to a HEAD request is a little weird,
but i am ok with that. If you want a detailed error response you can
always repeat the HEAD as GET.

Peter
barelyenough.org

[Mike Schinkel]

On May 31, 2012, at 5:19 PM, Peter Williams wrote:

For example, let's assume I tried to access a past bank statement as

"application/pdf" via the API but the bank has rules that lock down

statements when the account is not in good status. A "409 Conflict" would

seem to be the right response code, but it doesn't tell my why my account is

not in good status; it would be preferable to be told it's because the

account is overdrawn vs. the State department has frozen the account, etc.

(NOT speaking from experience on the latter here. :)

Well, in this situation i would prefer a prose description of why the
account is locked. If the user agent accepts HTML i would send the
error description in HTML if not i would use plain text. There is
nothing the client can do to fix the problem so burying the
description of the situation in a machine readable format just makes
understanding the problem more difficult.

Exactly.  But where is that prose consistently available? It's not if I'm doing AJAX, for example, as the user doesn't get to see it unless the client-side code displays it.  Which is can't without headers for certain response status codes and certain verbs.

It seems reasonable to send error messages via "text/plain", but it feels

wrong to return "text/plain" if the header is "Accept: application/json"

or "Accept: application/pdf" only.

The real question is how are clients going to use the response. If you
are really just sending a human readable description of the error then
plain text or HTML seems most appropriate. If you are trying to convey
some information to allow the user agent to recover from the error
then you'll need a machine readable format.

Exactly.  But currently it's ambiguous what will be returned and there's no way to inspect the response to be sure.

I'd be included to just put the error format in the accept header
field with a low q value.

Given the existing spec without extensions, yes, but that doesn't give the API any explicit guidance on the error mime types the client can handle; it would be valid to return a non-error with that mime-type.

Hmm.  Not every client can be that robust; it would be impossible to

anticipate every potential type even for the best clients unless you mean

just give up rather than fail. Still, not the best, especially for AJAX as

it might be hard to give the user an idea why things failed.

I disagree. If you are interacting with the user synchronously and you
get a non-success response in a media type you don't understand you
can just display and "Unknown error occurred" with a details button
that show the user the full response body. If a human is not
immediately available you can do the same thing but just shove it in
the log file.

That's not a disagreement, that's the "just give up rather than fail" scenario I stated in the "unless..."  :)

IMO it would be nice to be able to do better.

Hmm.  Workable, but could it not be better by explicitly addressing error

handling?

Don't see any better way to do it. Recovering from errors is
application specific so it is going to be pretty difficult to
generalize.

I see a better way. The prose can be included in a header directly or via a link, i.e. http://example.com/error-descriptions/123.html

For complex error response, a response header could specify that it's returning a mime-type specified in the request format and/or it could provide a URL for that mime type in the case of responses that are not allowed to have a message body.

None of this is application specific.

Also, according to the HTTP spec for the Message Body[1] returning an error

message in the message body would violate the spec in these cases given the

"MUST NOT" wording:

"All responses to the HEAD request method MUST NOT include a message-body,

even though the presence of entity- header fields might lead one to believe

they do. All 1xx (informational), 204 (no content), and 304 (not modified)

responses MUST NOT include a message-body."

Yeah, handling an error response to a HEAD request is a little weird,
but i am ok with that. If you want a detailed error response you can
always repeat the HEAD as GET.

But not ok with it.  And it's not just for HEAD but also for 1xx, 204 and 304 status codes. Which is why I persist. :)

-Mike

[Peter Williams]

On Thu, May 31, 2012 at 3:05 PM, mca <m...@amundsen.com> wrote:
> On Thu, May 31, 2012 at 4:55 PM, Peter Williams <pe...@barelyenough.org>
>

> In most of my apps "409" is not enough information for the user to correct
> the problem. it's true that in some cases the write representation sent to
> the server has only one possible field that could generate a conflict and it
> is reasonable to expect the user/dev to understand which single field that
> is. however, in many cases the write representations i send have more than
> one field that could generate a sever-side conflict and/or the user is not
> in a position to know which field is the culprit (inlcuding cases where the
> offending field is "hidden" from the user's view). YMMV

I agree that the status code is rarely sufficient to allow problems to
be solved. However, problems are almost always solved by a human, not
automatically. Given that target audience of error responses is
usually humans why not use a format well suited to displaying
information to a human like HTML or text?

> I get the impression that you are answering this from the POV of M2M-only
> work. is that correct?

Only sort of. I do think this issue is mostly an open question for M2M
scenarios. For most M2H scenarios it is pretty clear that HTML is the
right way to handle error responses. HTML is just about as good as it
get for conveying information to human, so why would you use anything
else? Most of the M2H web already sends error responses as HTML and it
works pretty well. Even when the M2H interaction is ajaxic, HTML
(fragment) error responses still make great sense unless you think the
javascript might be able to automatically recover (which makes it feel
like a M2M type scenario).

Just to be clear, i don't think there are any media types which are
wrong for error responses. Just that some work better than others.

Peter
barelyenough.org

[Peter Williams]

On Thu, May 31, 2012 at 3:33 PM, Mike Schinkel <mi...@newclarity.net> wrote:
> That's not a disagreement, that's the "just give up rather than fail"
> scenario I stated in the "unless..."  :)

Well, that is what i meant by "handle failure responses gracefully
regardless of the media type of the body". If the client doesn't
understand the content type it can use the status code to construct a
generic error message and then move on with life. :)

Peter
barelyenough.org

[mca]

Yeah, we're completely talking past each other...

when i see you write "why not use a format well suited to displaying information to a human like HTML or text?" I am confused; what do you *think* i have been suggesting?

1) i am NOT advocating for any special header field with which to report "errors"

2) i have already (early in this thread) outlined my approach (error object w/ in custom media type, declare error block w/ in existing media type, use link header for cases where the first two don't apply) for sending app-specific information about errors.

Also I am baffled by this exchange between you and me:

me: HTTP status codes are almost _never_ sufficient for carrying application-level error information.

you: I disagree. 

me: In most of my apps "409" is not enough information for the user to correct the problem. 

you: I agree that the status code is rarely sufficient to allow problems to be solved.

have you switched from "sufficient" to "sufficient to solve a problem"? IOW, have you disagreed w/ my general case only to agree w/ one of my offered specific specific cases? do we have a "scope" problem here?

finally, what is it you think we disagree upon here (if anything)?

 

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Mike Kelly]

On Thu, May 31, 2012 at 11:34 PM, mca <m...@amundsen.com> wrote:
> Yeah, we're completely talking past each other...
>
> when i see you write "why not use a format well suited to
> displaying information to a human like HTML or text?" I am confused; what do
> you *think* i have been suggesting?
>
> 1) i am NOT advocating for any special header field with which to report
> "errors"
>
> 2) i have already (early in this thread) outlined my approach (error object
> w/ in custom media type, declare error block w/ in existing media type, use
> link header for cases where the first two don't apply) for sending
> app-specific information about errors.

a custom media type isn't well suited to displaying information to a
human, text/plain and text/html are

>
> Also I am baffled by this exchange between you and me:
> me: HTTP status codes are almost _never_ sufficient for
> carrying application-level error information.
> you: I disagree.
> me: In most of my apps "409" is not enough information for the user to
> correct the problem.
> you: I agree that the status code is rarely sufficient to allow problems
> to be solved.

afaict, Peter's initial disagreement was due to his belief that HTTP
error codes are sufficient for expressing the type of error
'mechanically' - i.e. there is no need for a machine-readable
representation of an error because HTTP status codes are enough.
However his later clarification was that more specific details of the
error which related specifically to the app (banking, CRM, whatever)
clearly go beyond the scope of HTTP (since they are app specific), but
that these details should be represented in a format that is well
suited to expressing information in a human-readable form (i.e. w/
ubiquitous human-readable types like text/plain or text/html) and not
a snow-flake custom media type based targeted at machines.

Cheers,
M

[Jørn Wildt]

One of the problems may be that people have different expectations for the error handling. Here are some different scenarios:

1) An HTML page for human interaction. The obvious choice for error encoding is HTML.

2) A simple ajax style web page. I am no expert on ajax frameworks, but text/plain and text/html should be easy to show to the user. A well known JSON object with the error message would be just as good.

3) An "advanced" ajax style web page may want to highlight specific input fields to show the user were to correct the errors. This would require a more formal encoding of field names and error messages for each of them, making JSON the most obvious choice.

4a) A "pure" machine-to-machine may not need more than the error message itself (text or HTML) since it probably won't be able to do anything intelligent with more formal/fine-grained error information.

4b) On the other hand - the M2M application might just have error situations which the machines could handle themselves if enough information was given, maybe something as simple as selecting a appropriate error queue to route the response to based on the error details.

As has been pointed out a couple of times now - error handling turns out to be an application specific thing and thus there is nothing in HTTP core that can be generalized beyond the status codes.

Interesting discussion. Thanks.

/Jørn

[Mike Schinkel]

On Jun 1, 2012, at 5:31 AM, Mike Kelly wrote:

a custom media type isn't well suited to displaying information to a

human, text/plain and text/html are

Except (at least) for when the API is used for AJAX and the response needs control information to be processed by the client Javascript.

-Mike

[Mike Schinkel]

One of the problems may be that people have different expectations for the error handling. 

Definitely!  (But I think you can replace "error handling" with any topic every discussed by humankind and it would still be true! :)

2) A simple ajax style web page. I am no expert on ajax frameworks, but text/plain and text/html should be easy to show to the user. A well known JSON object with the error message would be just as good.

The "well known" part here is key albeit "well known" headers could improve this; see next.

thus there is nothing in HTTP core that can be generalized beyond the status codes.

Disagree (as I've previously said.) Selected headers could specific a error description for when a message body is not allowed (either as plain text or a URL) and a header could indicate a mime type for an error message when it would be more useful than text/plain or text/html.

-Mike 

[The Amiable API]

Very well put, Mike.

A communication protocol is a set of rules about how to communicate. On top of these rules, an application has many other (business) rules and constraints that have nothing to do with communication. They apply to a monolithic version of the application as well. Enforcing these rules and constraints should not be done at the protocol (HTTP) layer.

Say your application handles purchase orders and no two purchase orders can have the same identifier. This constrain applies weather you are typing the purchase order directly into your mainframe or updating it remotely via a HTML form. A duplicate id is an application logic error, not a communication error, so you should not use a HTTP error code to signal it. The communication was done correctly. The server received and understood the message. The protocol is working. A HTTP error code would be akin of telling a person “Sorry, I cannot understand you” on the phone when what you mean is “Sorry, but I cannot do what you are asking”.

I agree that rethinking the communication is such a way that you don’t need to resort to HTTP error codes to signal business logic violations is often non-trivial, but it is well worth the effort, IMO.

Ferenc Mihaly
http://theamiableapi.com

[Peter Williams]

On Fri, Jun 1, 2012 at 1:44 PM, The Amiable API <fmi...@opentext.com> wrote:
> Say your application handles purchase orders and no two purchase orders can
> have the same identifier. This constrain applies weather you are typing the
> purchase order directly into your mainframe or updating it remotely via a
> HTML form. A duplicate id is an application logic error, not a communication
> error, so you should not use a HTTP error code to signal it. The
> communication was done correctly. The server received and understood the
> message. The protocol is working. A HTTP error code would be akin of telling
> a person “Sorry, I cannot understand you” on the phone when what you mean is
> “Sorry, but I cannot do what you are asking”.

Are you suggesting that in the duplicate id scenario above the server
should response with a 200 OK and inform the client of the failure in
the response body?

Peter
barelyenough.org

[The Amiable API]

Isn't 200 OK what we return when there is an error in HTML form data and we want the user to correct and resubmit?

In the case of programming errors, when the client developer (not the user) did something wrong, 400 Bad Request seems the most appropriate response.These are non-recoverable errors and should not happen in properly written and tested software. In this case, a link to the online documentation section where (hopefully) we explained what we expect should be sufficient. This response body is for the developer alone and should be ignored in released software.

So I would use either 200 or 400 depending if it is recoverable (user) or unrecoverable (programmer) error.  

Ferenc
http://theamiableapi.com       

On Friday, June 1, 2012 6:16:06 PM UTC-4, Peter Williams wrote:

[Mike Kelly]

On Sun, Jun 3, 2012 at 3:32 AM, The Amiable API <fmi...@opentext.com> wrote:
> Isn't 200 OK what we return when there is an error in HTML form data and we
> want the user to correct and resubmit?
>
> In the case of programming errors, when the client developer (not the user)
> did something wrong, 400 Bad Request seems the most appropriate
> response.These are non-recoverable errors and should not happen in properly
> written and tested software. In this case, a link to the online
> documentation section where (hopefully) we explained what we expect should
> be sufficient. This response body is for the developer alone and should be
> ignored in released software.
>
> So I would use either 200 or 400 depending if it is recoverable (user) or
> unrecoverable (programmer) error.

No, that's not a good approach, e.g. 401 is a prime example of where
this interpretation makes no sense.

The body should be used to further clarify the nature of an error
beyond the generalised semantics of the _most appropriate_ HTTP
response code, it should not remove a requirement to use the most
appropriate response code. 2xx codes are for responses where the
request was valid and its intent could be successfully serviced, so
they aren't appropriate if a user submits invalid form data.

The reason it's important to use the most appropriate response code is
that it makes the interaction more self-descriptive, so that it can be
properly understood 'out on the network' by intermediaries. For
example, this means that taking your approach of using the wrong
response code would lead to system that causes redundant cache
invalidations since the 2xx response codes would invalidate cached
responses unnecessarily whereas using a 4xx would not.

Cheers,
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[Duncan Cragg]

On 03/06/12 09:51, Mike Kelly wrote:
> On Sun, Jun 3, 2012 at 3:32 AM, The Amiable API<fmi...@opentext.com> wrote:
>> Isn't 200 OK what we return when there is an error in HTML form data and we
>> want the user to correct and resubmit?
>>
>> In the case of programming errors, when the client developer (not the user)
>> did something wrong, 400 Bad Request seems the most appropriate

>> response...

>>
>> So I would use either 200 or 400 depending if it is recoverable (user) or
>> unrecoverable (programmer) error.
> No, that's not a good approach, e.g. 401 is a prime example of where
> this interpretation makes no sense.

Many 4XX codes are defined in a way that crosses the boundary between
things that are the responsibility of the HTTP layer and its client
libraries, and things that need to be raised up to the domain layer,
perhaps to be sorted out with the user's help.

They still fall roughly within the remit of sorting out HyperText/Media
Transfer (HTTP) - they are generic and domain-independent - they don't
care that it was your jam recipe that was not found, protected, in
conflict, submitted wrongly, etc. HTTP only handles things at just below
the Media Type - HTML, HTML form.

4XX can simply be seen as 'Dear Domain: I, HTTP, don't know what to do,
but we've done something wrong, so here's my best guess at where we are'.

> 2xx codes are for responses where the
> request was valid and its intent could be successfully serviced, so
> they aren't appropriate if a user submits invalid form data.

So just to make sure I get what you've said here: would 400 be
appropriate in that case? For an HTML or browser interaction? And now
proxies and caches will behave differently than if it were 200? I can't
say I've got practical experience of this approach or its consequences,
so I'd appreciate some elaboration here. What cached result would be
affected? POST responses have to be explicitly marked cacheable anyway,
right?

Suppose you entered a form to build your own jam recipe, and you entered
cabbage for an ingredient. Say the server, at the domain level, knows
that that's ridiculous, and returns a response saying so.

I'd give that a 200, not a 400!

That's how I see it in the Object Network, and in the FOREST
interpretation of REST for M2M.

In fact, it's even better when going M2M: you've got the opportunity to
really cleanly separate HTTP - Hypermedia Transfer - from the Domain
interactions. Separate protocols and layers and library code. With some
4XX's being punted upwards.

I would say auth/401 is still HTTP layer, even if you ask for a password
the first time around. You can do that stuff in a generic,
domain-independent way, and should do. The Object Network will be
defining how to build an auth header, and about asking for the user to
enter passwords.

So we have two approaches here, which can be represented by at least two
named architectural choices that API designers have available to them:

- "The Object Network approach": separate domain from hypermedia
transfer and return 200 for domain errors, putting the info in the content.
- "The HAL approach": find the nearest matching HTTP error code for
both hypermedia transfer errors and domain errors.

Choose whichever works for your philosophy!! :-) Apologies if my obvious
bias has misrepresented your (Mike Kelly's) beliefs; not sure how much
HAL specifies here.

I think it's best if we simply agree to disagree and let people choose
what works for them. :-)

Cheers!

Duncan

[sune jakobsson]

Hi guys from RFC 2616, the responses are pretty much self-explained:

   10.1  Informational 1xx ...........................................57

   10.1.1   100 Continue .............................................58

   10.1.2   101 Switching Protocols ..................................58

   10.2  Successful 2xx ..............................................58

   10.2.1   200 OK ...................................................58

   10.2.2   201 Created ..............................................59

   10.2.3   202 Accepted .............................................59

   10.2.4   203 Non-Authoritative Information ........................59

   10.2.5   204 No Content ...........................................60

   10.2.6   205 Reset Content ........................................60

   10.2.7   206 Partial Content ......................................60

   10.3  Redirection 3xx .............................................61

   10.3.1   300 Multiple Choices .....................................61

   10.3.2   301 Moved Permanently ....................................62

   10.3.3   302 Found ................................................62

   10.3.4   303 See Other ............................................63

   10.3.5   304 Not Modified .........................................63

   10.3.6   305 Use Proxy ............................................64

   10.3.7   306 (Unused) .............................................64

   10.3.8   307 Temporary Redirect ...................................65

   10.4  Client Error 4xx ............................................65

   10.4.1    400 Bad Request .........................................65

   10.4.2    401 Unauthorized ........................................66

   10.4.3    402 Payment Required ....................................66

   10.4.4    403 Forbidden ...........................................66

   10.4.5    404 Not Found ...........................................66

   10.4.6    405 Method Not Allowed ..................................66

   10.4.7    406 Not Acceptable ......................................67

   10.4.8    407 Proxy Authentication Required .......................67

   10.4.9    408 Request Timeout .....................................67

   10.4.10   409 Conflict ............................................67

   10.4.11   410 Gone ................................................68

   10.4.12   411 Length Required .....................................68

   10.4.13   412 Precondition Failed .................................68

   10.4.14   413 Request Entity Too Large ............................69

   10.4.15   414 Request-URI Too Long ................................69

   10.4.16   415 Unsupported Media Type ..............................69

   10.4.17   416 Requested Range Not Satisfiable .....................69

   10.4.18   417 Expectation Failed ..................................70

   10.5  Server Error 5xx ............................................70

   10.5.1   500 Internal Server Error ................................70

   10.5.2   501 Not Implemented ......................................70

   10.5.3   502 Bad Gateway ..........................................70

   10.5.4   503 Service Unavailable ..................................70

   10.5.5   504 Gateway Timeout ......................................71

   10.5.6   505 HTTP Version Not Supported ...........................71

[Mike Kelly]

On Sun, Jun 3, 2012 at 2:58 PM, Duncan Cragg <mee...@cilux.org> wrote:
> On 03/06/12 09:51, Mike Kelly wrote:
>> 2xx codes are for responses where the
>> request was valid and its intent could be successfully serviced, so
>> they aren't appropriate if a user submits invalid form data.
>
> So just to make sure I get what you've said here: would 400 be appropriate
> in that case? For an HTML or browser interaction? And now proxies and caches
> will behave differently than if it were 200? I can't say I've got practical
> experience of this approach or its consequences, so I'd appreciate some
> elaboration here. What cached result would be affected? POST responses have
> to be explicitly marked cacheable anyway, right?

http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache-19#section-2.6

" A cache MUST invalidate the effective Request URI [...] when a
non-error response to a request with an unsafe method is received."

> Suppose you entered a form to build your own jam recipe, and you entered
> cabbage for an ingredient. Say the server, at the domain level, knows that
> that's ridiculous, and returns a response saying so.
>
> I'd give that a 200, not a 400!

Why? What would be the benefit in doing that? That is a client error,
client errors in HTTP are meant to result in 4xx responses.

> I would say auth/401 is still HTTP layer, even if you ask for a password the
> first time around. You can do that stuff in a generic, domain-independent
> way, and should do. The Object Network will be defining how to build an auth
> header, and about asking for the user to enter passwords.
>
> So we have two approaches here, which can be represented by at least two
> named architectural choices that API designers have available to them:
>
>  - "The Object Network approach": separate domain from hypermedia transfer
> and return 200 for domain errors, putting the info in the content.
>  - "The HAL approach": find the nearest matching HTTP error code for both
> hypermedia transfer errors and domain errors.
>
> Choose whichever works for your philosophy!! :-) Apologies if my obvious
> bias has misrepresented your (Mike Kelly's) beliefs; not sure how much HAL
> specifies here.

HAL does not enforce either one of these approaches over the other.
Why would it? It is just a media type that gives you a handful of
conventions for linking, basically.

Cheers,
Mike