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

Login failed or authentication token 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.

■

The user 's session has expired.

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 Service Unavailable

The server is currently unable to handle the request due to a temporary condition such as resource exhaustion or server maintenance.

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 and must be included in all subsequent requests from clients that authenticate to the integrated identity provider (see Create a Session Using Basic Authentication) or the SAML identity provider (see Create a Session Using SAML Authentication).

Note

Clients that authenticate to the OAuth identity provider can include either the x-vcloud-authorization header or the OAuth Authorization: Bearer header to authorize a request. See Create a Session Using OAuth Authentication.

X-VMWARE-VCLOUD-REQUEST-ID

If a request supplied 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-REQUEST-EXECUTION-TIME

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