Processing Response Packets

After a request message is received, the server validates it, attempts to perform requested operations, and returns a response packet to a client. If an operation is successfully performed, the response packet contains the following operation details:

• The result element with the child status element set to ok.
• Operation parameters. These parameters typically include the identifier and properties of the Expand resources affected by the operation.

Otherwise, the server reports an error. The errors are divided into check-up errors, service errors, and input errors. All errors are identified by an error code. Error code descriptions are found in the Expand API Protocol Reference > Error Codes section of the Expand API Reference.

Check-up errors

Incoming HTTP message 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 Protocol version specified is supported
• check-up of the sender's credentials
• check-up of the packet contents validity

Any of these checkups can fail which makes further checkups and operation execution impossible. Since the server side has got stuck at one of the preliminary steps (i.e., it has not come to executing the requested operation yet), the response packet is formed with the system_error element containing an error description.In this case, operations nested in a packet are not performed.

For example, the response received from the server at the attempt to use a non-existing version of the Protocol looks as follows:

<packet version="2.3.0.26">

  <system_error>

    <code>1102</code>

    <text>[XML] Cannot parse packet - invalid XML or DOM error. Error at file 'systemId', line
		 27, column 16: Unknown element 'gen_setup'.</text>

  </system_error>

</packet>

Service errors

If all checkups are passed through successfully, the server attempts to execute the requested operations in series. If an Expand fails to provide one of its services or some Expand resources are corrupted, the server signals this fact by adding the system element to the response packet and proceeds to the next operation in a packet. For instance, if the Plesk domain account data is corrupted, the server adds the following fragment to the response packet:

  <get>

    <system>

      <status>error</status>

      <errcode>4000</errcode>

      <errtext>Tried to convert "NULL" to a "j</errtext>

    </system>

  </get>

Input errors

These errors occur when a client provide incorrect data from Expand object model standpoint, or a client is not permitted to perform an operation. These errors occur, for instance, if a client tries to access an object that does not exist. The server indicates input errors by adding a result node to the response packet with the status node set to error.

A fragment of a response packet describing an input error is provided in the following sample:

<add>

	<result>

		<status>error</status>

		<errcode>4003</errcode>

		<errtext>[Operator] PleskAgent error. Error Plesk server answer: (1024) [PleskAgent - GENERAL] Reached limit. The limit on number of domains is reached for this client account.</errtext>

		<client_id>11</client_id>

		<server_id>2</server_id>

	</result>

</add>

Processing routine

Summing up, a client should perform the following sequence of actions when it receives a response packet:

1. Check if the packet contains the system element. This element signals that a check-up error occurred.
   • If the element is present in the packet, output the error description. Check-up errors typically occur if a request packet does not conform to the Protocol.
   • If the element is not present in the packet, go to step 2.
2. Process the details of each operation. For details on the syntax of operation-specific data returned by the server, refer to Supported Operations > [Operation-specific section] > Response Packet Structure.
   • If an operation failed, output the error description and proceed to processing details of the next operation.
   • If an operation succeeded, issue the success message and proceed to processing details of the next operation.

For the code of a client application that implements the routine, refer to the next chapter.