Specification for Fault Code Interoperability, version 20010516
Author: Dan Libby
Major Contributors:
- Charles Cook
- Dave Winer
- Eric Kidd
- John Wilson
- S. Alexander Jacobson
ChangeLog
1.0 (draft 1) | Initial draft release |
1.0 (draft 2) | Adding reserved range for implementation specific errors and differentiating between unknown encoding and incorrect char for encoding |
20010516 | changed system.interopFaultCodes to system.getCapabilities. changed version to date based integer which is useful for comparisons |
Charter
As the number of xml-rpc server implementations has proliferated, so has the number of error codes and
descriptions. The charter of this specification is to define a small set of error codes that are
common across most server implementations so that clients can programmatically handle common errors such as
"method not found" or "parse error".
Goals
- improved interoperability
- ease of implementation
- maintain xml-rpc spec compatibility
- maintain backwards compatibility with existing xmlrpc implementations and apps
- extensibility. both for this spec and for applications & implementations conforming to it
Decisions
- K.I.S.S. not trying to solve all the world's problems.
- namespaces are nice, but add complexity. this is a simple problem
- define general error classes only. specifics may be filled in via description
Reserved Error Codes
This spec reserves the numbers -32768 .. -32000, inclusive, for use as pre-defined xmlrpc error codes.
Any implementation which conforms to this spec should not allow the application to set an error code
within this range. Any error codes within this range not defined explicitly below are reserved for
future use. Any implementation which uses them is in non-compliance.Defined Error Codes
- -32700 ---> parse error. not well formed
- -32701 ---> parse error. unsupported encoding
- -32702 ---> parse error. invalid character for encoding
- -32600 ---> server error. invalid xml-rpc. not conforming to spec.
- -32601 ---> server error. requested method not found
- -32602 ---> server error. invalid method parameters
- -32603 ---> server error. internal xml-rpc error
- -32500 ---> application error
- -32400 ---> system error
- -32300 ---> transport error
In addition, the range -32099 .. -32000, inclusive is reserved for implementation defined server
errors. Server errors which do not cleanly map to a specific error defined by this spec should
be assigned to a number in this range. This leaves the remainder of the space available for
application defined errors.system.getCapabilities
system.getCapabilities is a
standard method for determining if a given capability
is supported by a given server. For our purposes, a capability may be defined as a layer on
top of xml-rpc for which a spec exists. Thus, support for standard faults is a capability.
Any server which conforms to this spec must implement system.getCapabilities and return a member struct
representing the faults capability. The struct shall be identified by the key "faults_interop". The
specUrl should be "http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php", and the specVersion
should be the integer 20010516. Here is an example response in pseudo-code:
struct {
faults_interop => struct {
specUrl => "http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php",
specVersion => 20010516
}
}
A fault or any other response indicates that the server is not in conformance with this spec, and
fault error codes should be treated as application defined error codes.