When designing a complex hypermedia API you will inevitably come across the situation where instead of returning the required resource, you need to return an error state. Currently, there is no hypermedia type registered with IANA to deal with this scenario, so it is left up to the API designer to construct and document a mime type that can be used to express an error state in the application.

Because of this, several people have come together and put together a proposal for the application/vnd.error media type. It has been documented over on Github and the mime type has been submitted for approval by IANA.

The intention for this media type is that it should be used when a client has made a request, however the server is unable to fulfil the request to to either a server side error (a code 5xx) or a problem with the client request (a code 4xx).

Although the client does NOT have to state that it explicitly will accept the application/vnd.error+xml or json mime type (via the ‘Accept’ header in the request), it makes a lot of sense to do so if the client can understand that response type. However, RFC2616 section 10 states:

HTTP/1.1 servers are allowed to return responses which are not acceptable according to the accept headers sent in the request. In some cases, this may even be preferable to sending a 406 response. User agents are encouraged to inspect the headers of an incoming response to determine if it is acceptable.

It is up to the implementor to decide whether the api should return a 406 (Not Acceptable) response if the client states it will not accept application/vnd.error+xml or json and an error is triggere, or if it should return the application/vnd.error+xml or json response anyway.

The specification for application/vnd.error is draft – if you have comments / suggestions or enhancements to the media type, let’s talk (comments on this blog, issues on github, twitter etc).

Tagged with →  
Share →

5 Responses to The error hypermedia type

  1. I suspect that there’s just too many MIME types around, too many ways in which they’re used, and too many application-specific errors, for a single content type to be able to express all the reasons a server might reject some content. (Maybe additional type information could be embedded in the body, but that way dragons lie…)

    Examples of application-specific errors that clients might want to understand: “unknown symbol at byte 3245”, “printer jammed”, “couldn’t detect faces in image at location x,y”, “customer does not exist”, “RAID failure”.

    Also, if a media type is in the “vnd” namespace, shouldn’t there be an actual vendor, or some equivalent? (“mozilla”, “ms”, etc.) RFC4288 doesn’t seem to require it, but I can’t find any examples where that isn’t the case. Was the media type discussed on the ietf-types mailing list before submission?

  2. blongden says:

    Michael, you’re probably right in that there are too many mime types around. The problem is that none of them are designed for specifically representing an error state. There was some consideration in including an application specific error code as a code element in the spec, however it conflicts with the HTTP status header. If you want your application to be more verbose in it’s error responses it’s perfectly ok to use a custom HTTP status code for that purpose if there is not already one suitable in all of the various RFC’s out there. Wikipedia has a pretty good list.

    The vnd namespace is a lot more relaxed on the peer review aspect of getting the mime type approved. It’s not been discussed on the ietf-types mailing list (but i’ll drop a post in there). The spec is in draft form, and there are several changes and enhancements on the way already. If you have any suggestions then please do let me know.

  3. Sorry I guess my comment wasn’t clear. The point about the large number of mime types is not that an error type is one too many, but that pretty much every one of the existing types could be rejected by a server in a way specific to that type. You might even want different error content types for the same input type: if an XML file is rejected, the server might send different error content types depending on whether it used libxml2 or xerces to do the validation. (And obviously the client could use content negotiation to indicate that it would prefer xerces-style errors, etc.–maybe it was written before libxml2 was invented, for example.)

    Regarding the recent addition of multiple languages within the response, why not handle that via content negotiation on Accept-Language, etc.?

  4. blongden says:

    Actually the intention is that con-neg *should* be used for the language negotiation. It’s just xml that can support multi lang using the xml:lang attribute and I wanted a way of representing the same thing in JSON (somewhat unsuccessfully IMO, blog post to follow about this subject!).

    I’m tempted to back out that facility in JSON to remove complexity from the format and just leave it as an option in the XML representation (and primarily use con-neg for it).

    My thinking behind having it is incase the server blows up (5xx response) before the con-neg has complete – but perhaps it’s over thinking it.

Leave a Reply

Your email address will not be published. Required fields are marked *