web services - SOAP faults or results object?

Question

I was having a discussion about this with a co-worker and we couldn't come to an agreement, so I wanted to get your thoughts. I have my own opinions on this, but I won't spoil it for you.

When should I be returning a SOAP fault and when should I be returning a result object that has error information? Assume this is for a generic web service that can be consumed by various systems (.NET, Java, whatever). The result object would have an isError flag, an errorType (similar to specific exception type), and a message.

Some points to consider:

1. Is a data validation error a fault?
2. Should there be a combination of faults (for very exceptional cases) and the results object (for "expected" errors)?
3. How would you group SOAP faults (critical [null reference] vs validation [zip code incorrect])?
4. Fail-fast vs having to remember to check for error
5. Best practices, patterns, standards, etc.

Links to articles are valid. Even though it sounds like I want your opinion, please stick to facts (x is better because of y and z...)

Answer 1

Most SOAP clients will convert faults into a runtime exception (if that is something the client language supports). With that in mind, I think you could rephrase the question as "When do I want to throw an exception instead of returning an error value"? I'm sure you can find lots of opinions about that API design in general and that topic in particular.

That said, returning an error is usually not helpful to the client:

1. The client needs to manually enumerate and handle your error codes vs. allowing the stub code to generate and throw an exception of the appropriate type. Using error codes prevents the client from using object-oriented techniques like handling exceptions by superclass.

2. If you don't make your error codes part of the WSDL; the client will have no documentation on what they are or when they occur. Typed faults are part of the WSDL and therefore (to some limited extent) self-documenting.

3. Fault messages can contain fault-specific context that the client can make use of for error reporting and recovery. For example, throwing an input validation fault containing the actual invalid input element and a reason. If you return a result with an error code and an opaque string, the client has little choice but to pass your error message on to the user, which breaks internationalization, UI consistency, etc.

To answer your specific questions:

1. A validation error is a fault. Imagine if you invoke the web service from an AJAX client with limited error handling ability; you want the service to return a 5xx HTTP code, not a 400 success code with some unexpected response.

2. No. APIs should provide consistent error reporting interfaces. WSDL design is API design. Forcing the client to implement two distinct error handlers does not make the client's life easier.

3. Fault design should mirror your request/response model and display information appropriate to the abstraction of the service. Don't design a NullReference fault; design a XYZServiceRuntimeFault. If clients frequently provide invalid requests, design a InvalidRequestFault, with appropriate subclasses so that clients can quickly figure out where the invalid data is.