The server part reports about two types of errors to the client software, which are checkup errors and execution errors (if it comes to executing the requested operation).
If an error of any type occurs, its description returned by Plesk server always contains the following parameters:
- status with value "error"
- errcode - error code, a unique number identifying the error
- errtext - error message, a human-readable description of the error
An error description is defined by the type resultType in the
common.xsd schema (in most cases) or by types based on it (depending on the operator).
Incoming HTTP packet passes through a number of check-ups on the server side before it is considered valid and ready for execution. Here are some of these check-ups:
- check-up of HTTP-POST header
- check-up of whether the XML API protocol version specified is supported
- check-up of the authentication method (login credentials or secret key)
- check-up of the user's ‘remote_access_interface’ permission state
- check-up of the packet validity
- check-up of the required agents availability in the current Plesk version
Any of these check-ups can fail, which makes further checkups and command execution impossible. Since the server side has stalled at one of the preliminary checkup steps (that is, it has not come to executing the requested operation yet), the response packet is formed with the following elements:
system containing an error description; defined by type resultType in the
output, an optional element containing a message taken from stderr (if not empty) of the failed component; defined by type garbageOutput in the
For example, the response received from Plesk XML API server at the attempt to use a non-existing version of the XML API protocol looks as follows:
<packet> <system> <status>error</status> <errcode>1005</errcode> <errtext>XML API protocol version not supported.</errtext> </system> <output> </output> </packet>
The list of error codes supported by Plesk XML API server is presented in the Error Codes section of the Plesk XML API Protocol Reference.
If all checkups have been passed through successfully, the selected agents try to execute the requested operations in series. If any operation fails, the related agent reports about the execution error. All reports are gathered by Agent Engine which forms a response packet based on the output XML schemas. For example, if creation of a domain failed, the domain operator will form an error response using the
<packet> <domain> <add> <result> <status>error</status> <errcode>2300</errcode> <errtext>Failed to add domain.</errtext> </result> </add> </domain> </packet>
Note: Response packet can report about more than one execution error. This is possible if the incoming packet requests for more than one operation and some (or all) of them fail. Also, starting from version 220.127.116.11 of XML API, the response packet can contain multiple operator sections if the incoming packet requested operations on multiple Plesk objects.