VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

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

Content feedback and comments