Error information returned by web services
David Valentine
Ideally, we would use Detailed Soap faults, but .Net 2.0 does not make this simple. So below is a simplified version. Basically, a SOAP request returns a SOAP fault. This fault is a WaterOneFlowException + Message, if it is a user error, a WaterOneFlowServer exception + message if it is our error, or a WaterOneFlowSourceException + Message if it is somewhere else besides the server (eg web site or database).
There are also REST mappings that are becoming necessary.
| Error | Exception Object | REST | Soap 1.2 !! |
|---|
| Bad Parameter | WaterOneFlowException | 400 Bad Request | SOAP-1.2:Client |
| Site Not Found | WaterOneFlowException | 400 Bad Request | SOAP-1.2:Client |
| Variable Not Found | WaterOneFlowException | 400 Bad Request | SOAP-1.2:Client |
| Server Problem | WaterOneFlowServerException | 500 Internal Server Error | SOAP-1.2:Server |
| Source issue | WaterOneFlowSourceException | 503 Service Unavailable | SOAP-1.2:Server |
| No Values for requested period | none return empty values | none return empty values | none return empty values |
BELOW NEEDS TO BE UPDATED
Issue:
Errors are too generic, and we need to specify whether a server error occurred, or if a client input occurred.
Proposal:
- Recode error messages to return more detailed messages
- Return the two of the standard codes defined in .Net
- Return SubCodes for specific details
- Return detailed error messages:
Three Two Standard Soap Fault codes (partially taken from MSDN SoapException Codes)| SOAP-1.2:Client | A client call was not formatted correctly or did not contain the appropriate information. For example, the client call might not have the proper authentication or a location parameter. It is generally an indication that the message must be changed before it is resent. |
| SOAP-1.2:Server | An error occurred during the processing of a client call on the server, however, the problem is not due to the message contents. For example, an upstream server might not respond to a request due to network problems. Typically, with this type of exception, the client call might succeed later. If an XML Web service throws an exception, other than SoapException and the client calls using SOAP, ASP.NET converts the exception to a SoapException, setting the Code property to Server and throws it back to the client. |
External SOAP-1.2:Server | An error occurred while accessing an eternal service, such as the USGS, or an external database. |
Soap Fault Error Messages:
Client Errors:
These are problems with information submitted by a client.
| BaseCode | Cause | Message | Note |
|---|
| Client | Location Not Found | The Location XXX was not found. {optional details} || | |
| Client | Variable Not Found | The Variable XXX was not found. {optional details} |
| Client | No Values | No values we returned for the request. (DO WE WANT THIS, OR IS EMPTY VALUES OK?) |
| Client | Bad Parameter | Parameter XX was incorrect. Please resubmit. Possible cause: XXX || Bad Dates, or other issues. |
Server Errors:
| BaseCode | Cuase | Message | Note |
|---|
| Server | Local Server Error | Local Service Issue. {optional details} | Eg. Simple Error message |
| Server | Service Offline | Service is known to be down. If urgent, please contact XXXX. | What happens if a |
| Server | Service Error | Parameter XX was incorrect. Please resubmit. Possible cause: XXX | Uncaught exception. Will need to be fixed in the codebase. |
External Service Errors
SubCodes:
BaseCode DetailCode Message Note
External RemoteServiceError The external data source (XXXX) is not available. Eg USGS web site inaccessible, or a page we are scraping has changed
How to examine a SoapFault from a client
Try catch with SoapException
- Something for non-connect
Look for Code: - ClientFaulCode
- ServerFaultCode
Programming server side
References:
Soap protocol discussion:
http://hadleynet.org/marc/whatsnew.html
====