XML-RPC.NET Error Handling

Errors can occur at various stages of an XML-RPC call. XML-RPC.NET returns all errors to its clients via exceptions.

Error handling is problematical in XML-RPC. The Fault Response can be used to return an error code and description but there is no way of differentiating between an application error and a protocol level or internal error, for example if the XML-RPC code on the server throws an exception or cannot match request parameters to the method being called.One approach is to define a well-known set of error codes which will be used by all XML-RPC implementations but this suffers from the drawback that this set of error codes cannot be guaranteed to never conflict with error codes that an application may need to return, for example if the error codes originate from some other software that the application is calling.

To avoid potential clashes between application error codes and internal XML-RPC error codes, XML-RPC.NET uses the Fault Response solely for application error reporting and protocol level error conditons are returned via the HTTP status code. This might seem a rather ugly mixing of layers within the XML-RPC stack but the XML-RPC spec defines XML-RPC only in the context of HTTP, i.e. as an extension to HTTP in a similar vein to WEBDAV, and not as something which uses HTTP as one of possibly many transports. It also has the advantage of being a fully working solution which does not rely on extensions to the XML-RPC spec.

If the XML-RPC spec were ever to be extended to allow XML-RPC via a different transport mechanism then the extension could define its own way of returning protocol level errors.

An example of prior art for extending the use of HTTP status codes are the WEBDAV extensions to HTTP as described in RFC 2518. This defines two new client error code and one new server error code.

Errors occuring on the client-side are reported by throwing an instance of XmlRpcException and those occurring on the server-side are reported by throwing an instance of XmlRpcFaultException.

Server-Side Application Errors

XML-RPC returns application server-side errors to the client via the Fault Response:

<?xml version="1.0"?>
<methodResponse>
  <fault>
    <value>
      <struct>
        <member>
          <name>faultCode</name>
          <value><int>666</int></value>
        </member>
        <member>
          <name>faultString</name>
          <value><string>Devide by zero.</string></value>
        </member>
      </struct>
    </value>
  </fault>
</methodResponse>

The server application returns a Fault Response by throwing an instance of XmlRpcFaultException containing a fault code and a fault description:

if (b == 0)
  throw new XmlRpcFaultException(666, "Divide by zero.");

XML-RPC.NET converts this into the XML Fault Response and returns this to the client via a status 200 (Ok) HTTP response.

On the client side XML-RPC.NET parses the Fault Response and handles this on the client-side by throwing an exception of type XmlRpcFaultException. This can be caught in the usual way:

try
{
  int result = MathProxy.Divide(a, b);
}
catch (XmlRpcFaultException fex)
{
  Console.WriteLine("Error: {0} {1}", fex.FaultCode, fex.FaultDescription);
}

Client-side Errors

The client side of XML-RPC.NET may detect errors, for example if the Proxy class being used is not suitable or if the server returns an invalid response. These are reported by throwing an exception of one of several types derived from class XmlRpcException.