Response Format

API HTTP response messages use standard HTTP response codes to designate high-level status (success, failure, etc.) and simple XML payload in the response body to provide additional method specific data or specific error messages.

HTTP Response Codes

Zend Server Web API operations will return standard HTTP response codes in order to indicate overall success or failure. In case of an error, the HTTP status code may further indicate the nature of the problem, and a specific error code contained in the response body will indicate the specific nature of the error.

The following HTTP response codes may be used:

• 200 OK - The operation has completed successfully.
• 202 Accepted - The operation was accepted and is being processed, but is not complete yet.
• 4xx - HTTP status codes between 400 and 499 are used to designate a client-side error. For example, a missing request parameter or an authentication error.
• 5xx - HTTP status codes between 500 and 599 are used to designate a server-side error. For example, a temporary locking issue or an unexpected error in the server operation.

Additional information about HTTP response codes for error responses is available in Error Responses, as well as in the documentation for each method.

HTTP Response Headers

The following HTTP response headers will be included in API responses:

• Content-type - Unless stated otherwise, these will be “application/vnd.zend.serverapi+xml; version=<API version>”. For more information about API versions see API Versioning Negotiation.

HTTP Response Body

The Web API HTTP response body will almost always contain an XML document of the following format:

<?xml version="1.0" encoding="UTF-8"?>
<zendServerAPIResponse >
   <requestData>
    	<apiKeyName>angel.eyes</apiKeyName>
   	<method>clusterGetServerStatus</method>
  </requestData>
  <responseData>
    [response data here...]
  </responseData>
</zendServerAPIResponse>

All API responses are enclosed in <zendServerAPIResponse> tags, and contain two sections: <requestData> which includes some reference information about the request; and <responseData> which includes the response data.

The content of the <responseData> section differs depending on the specific method called. Refer to the method's specific documentation for additional information.

In error responses, the <responseData> section is replaced with an <errorData> section. See Error Responses for additional information.

 

Some Web API methods will not return an XML document in case of a successful operation - specifically, methods that export large amounts of binary data such as the configurationExport method. In such cases, this is specifically indicated in the method's documentation. Note that you can check the value of the Content-type response header in order to know in advance what kind of content to expect in the response.

Error Responses

In a response representing an error, the <responseData> XML section is replaced with the <errorData> XML section, which has the following format:

<errorData>
  <errorCode>serverDoesNotExist</errorCode>
  <errorMessage>A server with the specified ID does not 
 exist in the cluster</errorMessage>
</errorData>

Where:

• <errorCode> is a short alphanumeric constant string that represents the specific error.
• <errorMessage> is a human readable, native language explanation of the error.

In addition, some error responses may include additional elements in the <errorData> container, with additional information relevant to the specific error.

Generic Error Codes

The following generic error responses are possible for any operation:

HTTP Code	Error Code	Description
400	missingHttpHeader	A required HTTP header is missing.
400	unexpectedHttpMethod	An unexpected HTTP method where GET is used but POST is expected.
400	invalidParameter	One or more request parameters contains invalid data.
400	missingParameter	The request is missing a required parameter.
400	unknownMethod	An unknown Zend Server API method.
400	malformedRequest	The server is unable to understand the request.
401	authError	An authentication error occurred because of an unknown key or invalid request signature.
401	insufficientAccessLevel	The user is not authorized to perform this action.
401	timeSkewError	The request timestamp deviates too much from the server time.
405	notImplementedByEdition	The method is not implemented by this edition of Zend Server.
406	unsupportedApiVersion	The API version is not supported by this version of Zend Server.
500	internalServerError	An unexpected error occurred on the server side.
500	serverNotConfigured	This Zend Server installation was not yet initialized (the user did not go through the initial setup wizard).
500	serverNotLicensed	Zend Server does not have a valid license, which is required to perform this operation.

Refer to the documentation of a specific method for details about additional possible errors specific to each method.