All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content-Type header. Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty.

Response Content

Response content depends on the requested operation. The response to a GET request is typically the complete representation of an existing object. The response to a PUT or POST request always contains values for the href, name, and id attributes of the object being created or updated. It also contains at most one Task element that you can retrieve to track the progress of the operation. When the Task completes with a status of success, a GET request to the object's href returns all properties of the object. If the Task completion status is not success, the object is in an indeterminate state, and should be deleted.

HTTP Response Codes

A vCloud API client can expect a subset of HTTP status codes in a response.

HTTP Status Codes that the vCloud API Returns

Status Code

Status Description

200 OK

The request is valid and was completed. The response includes a document body.

201 Created

The request is valid. The requested object was created and can be found at the URL specified in the Location header.

202 Accepted

The request is valid and a task was created to handle it. This response is usually accompanied by a Task element.

204 No Content

The request is valid and was completed. The response does not include a body.

400 Bad Request

The request body is malformed, incomplete, or otherwise invalid.

401 Unauthorized

Any of:

■

Login failed.

■

Authentication token has expired

■

The user 's session has expired.

403 Forbidden

Any of:

■

One or more objects specified in the request could not be found in the specified container.

■

The user is not authenticated or does not have adequate privileges to access one or more objects specified in the request.

404 Not Found

Usually indicates a malformed request URL or request body.

405 Method Not Allowed

The HTTP method specified in the request is not supported for this object.

406 Not Acceptable

The resource identified by the request is not capable of generating a response of the type specified in the request's Accept header.

409 Conflict

The object state is not compatible with the requested operation.

415 Unsupported Media Type

The resource identified by the request does not support a request of the specified Content-Type and HTTP method.

500 Internal Server Error

The request was received but could not be completed because of an internal error at the server.

503 The cell is currently busy and cannot accept incoming requests. Please try again later.

The server is currently unable to handle the request due to too many requests. When the server recovers, the event The cell accepting new requests is posted.

504 Gateway Timeout

The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the request URL.

Response Headers

The following HTTP headers can appear in responses to vCloud API requests:

x-vcloud-authorization

This header is returned with the Session response after a successful log-in to the integrated identity provider. As of API version 30, it is deprecated in favor of the X-VMWARE-VCLOUD-ACCESS-TOKEN value returned when you create a Session. If backward compatibility is a concern, you can supply x-vcloud-authorization instead of an Authorization header in most requests that do not fan out to members of an organization or site association. See Configuring and Managing Multisite Deployments.

X-VMWARE-VCLOUD-REQUEST-ID

If a request supplies an X-VMWARE-VCLOUD-CLIENT-REQUEST-ID header, the response contains an X-VMWARE-VCLOUD-REQUEST-ID header whose value combines the value in the X-VMWARE-VCLOUD-CLIENT-REQUEST-ID with a unique ID. This value is added to every vCloud Director, vCenter, and ESXi log message related to processing the request, and provides a way to correlate the processing of a request across all participating systems. If a request did not supply a X-VMWARE-VCLOUD-CLIENT-REQUEST-ID header, the response contains an X-VMWARE-VCLOUD-REQUEST-ID header with a generated value that cannot be used for log correlation.

X-VMWARE-VCLOUD-ACCESS-TOKEN

The Session response to a successful login request includes an X-VMWARE-VCLOUD-ACCESS-TOKEN header whose value is an encoded key that you can use, along with the value of the X-VMWARE-VCLOUD-TOKEN-TYPE header, to construct an Authorization header to include in subsequent requests in place of the deprecated x-vcloud-authorization header.

X-VMWARE-VCLOUD-CEIP-ID

The presence of this header indicates that this site participates in VMware’s Customer Experience Improvement Program (“CEIP”). Details regarding the data collected through CEIP and the purposes for which it is used by VMware are set forth in the Trust & Assurance Center at http://www.vmware.com/trustvmware/ceip.html. You can use the cell management tool to join or leave VMware's CEIP for this product at any time. See the "Cell Management Tool Reference" in the vCloud Director Administrator's Guide.

X-VMWARE-VCLOUD-TOKEN-TYPE

If a response includes an X-VMWARE-VCLOUD-ACCESS-TOKEN header, it also includes an X-VMWARE-VCLOUD-TOKEN-TYPE header specifying the type of the X-VMWARE-VCLOUD-ACCESS-TOKEN.

X-VMWARE-VCLOUD-REQUEST-EXECUTION-TIME

The execution time, in milliseconds, of the request that generated this response.