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 VMware Cloud Director API client can expect a subset of HTTP status codes in a response.

Table 1. HTTP Status Codes that the VMware Cloud Director 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 VMware Cloud Director 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 in Your VMware Cloud Director.
X-VMWARE-VCLOUD-REQUEST-ID

The X-VMWARE-VCLOUD-CLIENT-REQUEST-ID header must contain only alpha-numeric characters or dashes. The header must contain at least one alpha-numeric character, and VMware Cloud Director shortens it if it's longer than 128 characters long. The X-VMWARE-VCLOUD-REQUEST-ID response header is formed from the first 128 characters of X-VMWARE-VCLOUD-CLIENT-REQUEST-ID, followed by a dash and a random UUID that the server generates. If the X-VMWARE-VCLOUD-CLIENT-REQUEST-ID header is invalid, null, or empty, the X-VMWARE-VCLOUD-REQUEST-ID is a random UUID. VMware Cloud Director adds this value to every VMware Cloud 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 does 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 VMware Cloud 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.