Web API Reference Guide > Generic Request/Response Format > Response Format

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:

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:

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 xmlns=“http://www.zend.com/server/api/1.0”>

   <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:

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.

 

Read Also

  Request Format