Handling Validation Errors

[Mr Marbles]

Brian G. and I got to talking briefly on this subject and thought that
it would be a good question to pose to this group.

As an example; Let's say you have a web service endpoint dedicated to
handling requests to create a new domain object - like a Person.

PUT /person

It's a reasonable scenario to want to validate the request to ensure
all of the required information is present in the request in order to
establish the new record. If validation fails - what http status code
is best suited for the response? For myself, I keep returning to 500
- even though it's not a hard-failure, no exception is thrown per se.

What is the opinion of this group?

Thanks,

- Brian

[WebFlint]

You bring up a good point. I obsess about status codes, but I
haven't seen a really loud voice on what to use for applications.
Most of the status codes I find seem to be more geared towards
hardware or network software with little attention or context to an
end web application.

I would LOVE to see something that documented what effect status codes
had on software and hardware.

Personally though, I have coded these as 412 errors (precondition
failed). I like to think the issue with the client request and not
the server. I have very little evidense I gain anything by this
though so if there is a better one I'd like to know. I've just
documented the error and left it up to the coder accessing the API to
deal with it.

I really find this chart helpful:

http://thoughtpad.net/alan-dean/http-headers-status.gif

[websolete]

My opinion:

• if the verb isn't allowed: 405 Method Not Allowed
• if the request isn't of an acceptable mime-type: 415 Unsupported Media
• if the request is invalid or not well-formed xml (or the like): 400 Bad Request
• if the request doesn't contain all required info: 400 Bad Request or 417 Expectation Failed

I also believe it is imperative to return details of the error beyond the status code, unless its completely obvious what the error was. 

For example, say you allow application/xml only and receive an application/json request body, and you return a 415; in this case, I think its optional to include error details (whether in an additional response header or in the response itself) that says 'hey, i only accept application/xml'.  Thats what API documentation is for, and including it at runtime is purely a developer convenience, since the STATUS CODE is the actionable item (and is static across all applications and implementations), and additional error details may or may not be used for programmatic handling of errors (every application will have a different way of describing an error in text and doesn't make for a good standardization point).

On the other hand, say you have invalid xml in the request and return a 400.  In this case I believe its required by a good api to include 'invalid or not well-formed xml' in the error details.  Otherwise, there would be no way to distinguish that from 'you didn't send me all required information', assuming you do a 400 for that case as well.

Ultimately, my view is this: the response code is the signal to the consumer about the state of their request and whether they need to do something additional in order for it to be successful.  Any additional details, whether sent in a response header or in the response body, are for the developer's convenience and shouldn't be relied upon to be consistent across applications, therefore making it a poor candidate to simply be echoed back to the user.  One other thought on this is that I am an advocate (and have thought of using it in my own api but haven't as of yet) of a 'standardized' response header containing 'sub-status codes', which could be used to attempt to create a more meaningful, standardized way of returning additional info using additional numbers; e.g. 400.1 Missing Required Info, 400.3 Invalid XML, etc.  Since it would be part of the api, it could arguably be termed a proprietary standard and would be documented.

I fully agree that it would be great if there was some definitive implementation guideline stating which code to use for what scenario using real-world conditions that everyone would follow.  From what I've seen, its really just opinions out there at this time (a decade later, bleh).

Kevin

[Mr Marbles]

I completely agree - sub-codes would make a world of difference.
Thanks for your responses! This will certainly help me in my own
development efforts.

On Apr 21, 11:36 pm, websolete <websol...@gmail.com> wrote:
> My opinion:
>
>    - if the verb isn't allowed: *405 Method Not Allowed*
>    - if the request isn't of an acceptable mime-type: *415 Unsupported Media
>    *
>    - if the request is invalid or not well-formed xml (or the like): *400
>    Bad Request*
>    - if the request doesn't contain all required info:* 400 Bad Request or
>    417 Expectation Failed *