SOAP error or result object?

Question

I discussed this with an employee, and we could not agree, so I wanted to get your thoughts. I have my own opinions on this, but I will not ruin it.

When should I return a SOAP error and when should I return an object containing error information? Suppose this is for a general web service that can be used by various systems (.NET, Java, independently). The result object has an isError flag, an errorType type (similar to a specific type of exception), and a message.

Some points to consider:

• Is a data validation error an error?
• Should there be a combination of errors (for very exceptional cases) and a result object (for "expected" errors)?
• How would you group SOAP errors (critical [null link] versus validation [wrong postcode])?
• Fail-fast vs must be remembered to check for errors
• Best practices, templates, standards, etc.

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

Answer 1

Most SOAP clients translate errors into runtime exceptions (if that is what 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 the error value"? I am sure that you can find many opinions about this API design in general and in this topic in particular.

However, returning an error usually does not help the client:

• The client needs to manually list and process the error codes compared to the stub code being generated and choosing the appropriate exception type. Using error codes prevents the client from using object-oriented methods, such as handling exceptions using the superclass.

• If you do not make your error codes part of the WSDL; the client will not have documentation about what they are or when they occur. Typed errors are part of WSDL and therefore (to some extent) self-documenting.

• Fault messages may contain a situation-specific context that the client can use for error reporting and recovery. For example, resetting an input validation error containing a valid invalid input element and reason. If you return the result with an error code and an opaque string, the client has little choice but to pass the error message to the user, which violates internationalization, user interface consistency, etc.

To answer your specific questions:

• Verification error is an error. Imagine if you are calling a web service from an AJAX client with limited error handling capability; you want the service to return an HTTP 5xx code, not a 400 success code with an unexpected response.

• No. APIs must provide consistent error reporting interfaces. WSDL design is an API design. Forcing the client to implement two different error handlers does not make life easier for the client.

• The failure design should reflect your request / response model and display information corresponding to the service abstraction. Do not throw a NullReference error; design XYZServiceRuntimeFault. If clients often provide incorrect requests, create an InvalidRequestFault with the appropriate subclasses so that clients can quickly determine where the invalid data is.

Answer 2

The result object should contain only results. If your result object provides a list of errors that occurred on another system, this is an example of when you can have the "isError" flag; otherwise you cannot, because the result is valid or not.

You should always use SOAPFault when an error occurs. Validation is a mistake, and this is the devil's trap who believes that the verification is reliable as less serious than the inability to open the database. Both cases have the same effect - the operation cannot be performed on request.

Therefore, you must use result objects for results and SOAP Faults for anything that interferes with the actual result object; including, but not limited to, errors, verification errors, warnings, bus errors, etc.

In the previous days there were no exceptions, and as a result, many APIs became incompatible, and most APIs differed in how to return the error. It was (and still is) terrible, confusing and often slowing down because you need to look for how each API entry returns an error, and often how to decrypt or learn more about the error.

• To handle checking with SOAPFaults / Exceptions is more logical when you think about it, and as soon as you think about it, it’s usually easier. You need to develop a validation validation class so that it contains sufficient information to identify the violating elements in a way that does not necessarily require an initial request. This way, you can handle verification errors more often.

• If the result object contains errors, they can only be within the scope of the results; for example, the Product is not in stock because someone in the warehouse cannot count within the inventory management area.

• It is not reasonable to distinguish between a critical error and a verification error; this, in my opinion, is not an acceptable comparison, because any assignment of a level of severity is very subjective. For example, in a system that provides information about chemicals to a firefighter, critical probably means that the truck on which the fire is mounted carries UN 1298 and UN No. 1436, and not an empty link when trying to load a warning schedule.

  Design errors so that they are clearly identified and handled accordingly. Make sure they provide sufficient information. Abrasive categorization is something superfluous when you have enough information, because Fault allows itself to be indexed.

• SOAPFaults turned into Exceptions are the surest way to speed things up.

• Best practices, links, etc.

  • SOA Exclusion Management: Ramesh Ranganathan

  • When exceptions are the rule: achieving robust and traceable service-oriented architectures

  • SOAP Error Recommendations

  • Use SOAP Faults to provide the appropriate level of detail to the developer during development and for the client while the web service is in production .

  • Web services use SOAP errors to report failures to clients. Errors can be generated from the SOAP structure in the case of invalid SOAP messages, invalid security tokens, or they can be generated from the service’s business logic itself .

  • If for some reason you sent a message that was not successful, you can return a response containing a SOAP error element that gives you status information, error information, or both. There can be only one SOAP error element in a message, and it must be an entry in the SOAP body. In addition, if there is a SOAP error element in the SOAP package, there can be no other elements in the SOAP body. This means that when you add the SOAP error element, you have actually completed the creation of the SOAP body.

  • SOAP Error Messages is the mechanism by which SOAP applications report upstream errors to nodes earlier in the message path. The goal of this section is to provide a complete and detailed explanation of SOAP errors so that you can properly handle them in your own web services.

Answer 3

I think the short answer is a soap error, if you do not know that the client will be equipped to handle the error returned as a result. I also thought about the analogy between exceptions and error results, as mentioned in other answers.

There are gray areas that could reasonably be considered as exceptions and as result errors depending on the needs of the client. You can then provide a parameter to a service that changes the way these types of errors return. By default, a SOAP error is used, but if the client sets a parameter to receive the error results, it indicates that it is ready to handle this as part of the result. For me, validation errors in this gray area. For most clients, they should be considered as malfunctions, but if the client wants to use the data for the user interface layout with verification errors, then returning verification errors, as part of the result can be more useful.

Answer 4

The rule that I adhere to in service design is as follows:

• business level response (even business exceptions) to response objects
• technical / level of integration errors in soap error

A service consumer can rely on the fact that every business response comes in response objects and presents it to service (business) users. Soap errors are used only when the business response cannot be delivered.

Soap bugs should trigger a warning / support action through monitoring.