Handling Errors

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 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 API RPC 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 got stuck at one of the preliminary checkup steps (i.e., 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 API RPC server at the attempt to use a non-existing version of the API RPC protocol looks as follows:

<packet version="1.40.2.0">

   <system>

       <status>error</status>

       <errcode>1005</errcode>

       <errtext>API RPC protocol version not supported.</errtext>

   </system>

   <output>…</output>

</packet>

The list of error codes supported by Plesk API RPC server is presented in the Error Codes section of the Plesk API RPC 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. E.g., if failed to create a domain, the domain operator will form an error response using the domain_output.xsd schema:

<packet version="1.4.2.0">

<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, beginning from version 1.4.0.0 of API RPC, the response packet can contain multiple operator sections if the incoming packet requested for operations on multiple Plesk objects.