vSphere Automation API Responses

The vSphere Automation API responds to every HTTP request with either a success or an error status code.

The vSphere Automation API uses a specific set of HTTP success and error codes for the responses. The response structure depends on the request type: some responses include a document body, some include a string, and some are empty.

Table 1. HTTP Success Codes

HTTP Code	Message Type	Message 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 its identifier is returned with the response.
202	Accepted	The request is valid and a task was created to handle it. The response usually contains a task identifier.
204	No Content	The request is valid and was completed. The response does not include a body.

Table 2. HTTP Error Codes

HTTP Code	Error Type	Error Description
400	ALREADY_EXISTS	An attempt was made to create an entity but an entity with the same name or identifier already exists in that context.
400	ALREADY_IN_DESIRED_STATE	Indicates that an attempt to change the state of a resource or service had no effect because the resource or service is already in the desired state.
400	CANCELED	Indicates that an operation was canceled due to an explicit request to do so.
400	FEATURE_IN_USE	Indicates that an action cannot be completed because a feature is in use. For example, trying to deactivate snapshots on a virtual machine that has a snapshot.
400	INVALID_ARGUMENT	Indicates that the values accepted for one or more parameters are not acceptable. Examples: A parameter value that is not of the expected type. A parameter value that is not in the required range. A parameter value that is different from the specifically allowed strings.
400	INVALID_ELEMENT_CONFIGURATION	Indicates that an attempt to modify the configuration of an element or a group containing the element failed due to the configuraton of the element. Examples: An attempt to move a host with a fault-tolerant virtual machine out of a cluster. An attempt to remove a host from a DRS cluster without putting the host into maintenance mode.
400	INVALID_ELEMENT_TYPE	Indicates that the server was unable to fulfill the request because an element of a specific type does not fit into a particular container type. Examples: An attempt to put a virtual machine into a folder that can only contain hosts. An attempt to attach an SCSI virtual disk to an IDE port.
400	INVALID_REQUEST	Indicates that the request is formed in such a way that the server is unable to process it. For example, sending an invalid JSON structure.
400	NOT_ALLOWED_IN_CURRENT_STATE	Indicates that the requested operation is not allowed with a resource or service in its current state. Examples: Trying to upgrade the virtual hardware version of a suspended virtual machine. Trying to power off, reset, or suspend a virtual machine that is not powered on.
400	RESOURCE_IN_USE	Indicates that the operation could not be completed because a resource is in use. Examples: Trying to remove a datastore when there is a virtual machine registered on a host attached to the datastore. Trying to add a virtual switch if the physical network adapter being bridged is already in use.
400	UNEXPECTED_INPUT	Indicates that the request body contains a parameter or a field whose name is unknown to the server.
400	UNSUPPORTED	Indicates that the operation is not supported by the underlying platform. Examples: Trying to hot-plug a CPU when the current virtual machine configuration does not support CPU hot-plugging . Trying to change the memory size to a value beyond the acceptable guest memory limits supported by the virtual machine's host.
400	UNVERIFIED_PEER	Indicates that an attempt to connect to an unknown or untrusted endpoint failed because the system was unable to verify the identity of the endpoint. Typically, the error data field of this error contains information about the endpoint. If you decide to trust the endpoint, the request can be resubmitted with an indication that the endpoint should be trusted. Examples: The client provides an IP address or an URL of an endpoint the system should communicate with using a TLS connection, but the endpoint's TLS certificate is self-signed, expired, or otherwise untrustworthy. The client provides an IP address of a host, with which the system must communicate through SSH, but SSH does not recognize the host's public key.
401	UNAUTHENTICATED	Indicates that the operation requires authentication and the user is not authenticated. For example, if the session identifier in the request header is missing or if it identifies a session that has expired.
403	UNAUTHORIZED	Indicates that the user is not authorized to perform the operation. For example, some operations might require that the user has one or more privileges over the operation or over a resource identifier but the user identified by the operation does not have the required privileges.
404	NOT_FOUND	Indicates that a specified resource could not be found. Examples: Trying to retrieve information about a virtual machine by passing an ID that does not match an existing virtual machine. Trying to remove a vSwitch by passing an ID that does not match an existing vSwitch.
404	OPERATION_NOT_FOUND	Indicates that the API infrastructure is unable to find the requested service or operation. For example, providing invalid REST API service name or method.
409	CONCURRENT_CHANGE	Indicates that a data structure, entity, or resource has been modified in comparison to some earlier point in time. For example, when the client is doing the write portion of a read-modify-write sequence and indicates that it wants the server to notify it if the data in the server has changed after the read was done, so that overwriting a change can be avoided.
500	ERROR	Indicates that the operation resulted in some error that does not fit into the standard error types.
500	INTERNAL_SERVER_ERROR	Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. Examples: The operation returns a value type that does not match the operation schema. The operation returns an error that is not included in the list of vSphere Automation API errors.
500	RESOURCE_BUSY	Indicates that the operation could not be completed because a resource is busy. For example, trying to power off a virtual machine that is in the process of being powered on.
500	RESOURCE_INACCESSIBLE	Indicates that the operation could not be completed because an entity is not accessible. For example, attempting to invoke some operation on a virtual machine when the virtual machine's configuration file is not accessible.
500	TIMED_OUT	Indicates that the operation did not complete within the allowed amount of time. The operation might or might not complete after the TIMED_OUT error is reported.
500	UNABLE_TO_ALLOCATE_RESOURCE	Indicates that the operation failed because it was unable to allocate or acquire a required resource. Examples: Trying to power on a virtual machine when there are not enough licenses to do so. Trying to power on a virtual machine that would violate a resource usage policy.
503	SERVICE_UNAVAILABLE	Indicates that the service you are trying to reach is unavailable. Examples: Trying to reach the server when it is too busy. Trying to reach the server while it's undergoing maintenance.