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).

Checkup errors

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 common.xsd schema
• output, an optional element containing a message taken from stderr (if not empty) of the failed component; defined by type garbageOutput in the plesk_common.xsd schema

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.

Execution errors

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 domain_output.xsd schema:

<packet>
<domain>
<add>
   <result>
       <status>error</status>
       <errcode>2300</errcode>
       <errtext>Failed to add domain.</errtext>
   </result>
</add>
</domain>
</packet>