Stops one or more Elastic Compute Service (ECS) instances in the Running state. After the operation is called, the state of the instances changes to Stopping and then to Stopped.

Description

  • If you call the DescribeInstances operation and the response contains {"OperationLocks": {"LockReason" : "security"}}, the instances are locked for security reasons and cannot be stopped.
  • If the economical mode is enabled for pay-as-you-go instances, you can set StoppedMode to KeepCharging to enable the standard mode for the instances. Then, after the instances are stopped in standard mode, you continue to be charged for them, and their instance type resources and public IP addresses are retained.
  • Batch operations are supported. You can use the BatchOptimization parameter to specify the batch operation mode.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes StopInstances

The operation that you want to perform. Set the value to StopInstances.

DryRun Boolean No false

Specifies whether to check the validity of the request without actually making the request. Valid values:

  • true: The validity of the request is checked, but the request is not made. Check items include the request format, instance status, and whether the required parameters are specified. If the check fails, the corresponding error message is returned. If the check succeeds, DRYRUN.SUCCESS is returned.
    Note If you set BatchOptimization to SuccessFirst and DryRun to true, only DRYRUN.SUCCESS is returned regardless of whether the check succeeds.
  • false: The validity of the request is checked, and the request is made if the check succeeds.

Default value: false.

RegionId String Yes cn-hangzhou

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

ForceStop Boolean No false

Specifies whether to forcibly stop the instance. Valid values:

  • true: forcibly stops the instance. This operation is equivalent to the typical power-off operation. Cache data that is not written to storage in the instance will be lost.
  • false: normally stops the instance.

Default value: false.

StoppedMode String No KeepCharging

The stop mode of the pay-as-you-go instance. Valid values:

  • StopCharging: economical mode. For information about how StopCharging takes effect, see the "Prerequisites" section in Economical mode.
  • KeepCharging: standard mode. After the instances are stopped in standard mode, you continue to be charged for them.

Default value: If the prerequisites required for enabling the economical mode are met and you have enabled this mode in the ECS console, the default value is StopCharging. For more information, see "Enable the economical mode" in Economical mode. Otherwise, the default value is KeepCharging.

BatchOptimization String No AllTogether

The batch operation mode. Valid values:

  • AllTogether: In this mode, if all instances are stopped, a success message is returned. If an instance fails the verification, all instances fail to stop and an error message is returned.
  • SuccessFirst: In this mode, each instance is separately stopped. The response contains the operation results for each instance.

Default value: AllTogether.

InstanceId.N String Yes i-bp67acfmxazb4p****

The ID of instance N. Valid values of N: 1 to 100

Response parameters

Parameter Type Example Description
RequestId String 1C488B66-B819-4D14-8711-C4EAAA13AC01

The ID of the request.

InstanceResponses Array of InstanceResponse

Details about instance-specific responses, which contain the states of each instance before and after the operation is called and the results of the operation.

InstanceResponse
Code String 200

The error code of the instance operation result. The return value 200 indicates success. For more information, see the "Error codes" section in this topic.

Message String success

The error message for instance operation. The return value Success indicates operation success. For more information, see the "Error codes" section in this topic.

InstanceId String i-bp67acfmxazb4p****

The ID of instance N.

CurrentStatus String Stopping

The current state of the instance.

PreviousStatus String Running

The state of the instance before the operation is called.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=StopInstances
&InstanceId.1=i-bp67acfmxazb4p****
&InstanceId.2=i-bp67acfmxazb4p****
&RegionId=cn-hangzhou
&ForceStop=false
&StoppedMode=KeepCharging
$BatchOptimization=SuccessFirst
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<StopInstancesResponse>
    <RequestId>FF53E96D-3F1A-42F0-8373-1C2B39D72D44</RequestId>
    <InstanceResponses>
        <InstanceResponse>
            <Message>success</Message>
            <InstanceId>i-bp67acfmxazb4p****</InstanceId>
            <PreviousStatus>Running</PreviousStatus>
            <CurrentStatus>Stopping</CurrentStatus>
            <Code>200</Code>
        </InstanceResponse>
        <InstanceResponse>
            <Message>success</Message>
            <InstanceId>i-bp67acfmxazb4p****</InstanceId>
            <PreviousStatus>Running</PreviousStatus>
            <CurrentStatus>Stopping</CurrentStatus>
            <Code>200</Code>
        </InstanceResponse>
        <InstanceResponse>
            <Message>The specified InstanceId does not exist.</Message>
            <InstanceId>i-TestID</InstanceId>
            <PreviousStatus/>
            <CurrentStatus/>
            <Code>InvalidInstanceId.NotFound</Code>
        </InstanceResponse>
    </InstanceResponses>
</StopInstancesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "FF53E96D-3F1A-42F0-8373-1C2B39D72D44",
  "InstanceResponses" : {
    "InstanceResponse" : [ {
      "Message" : "success",
      "InstanceId" : "i-bp67acfmxazb4p****",
      "PreviousStatus" : "Running",
      "CurrentStatus" : "Stopping",
      "Code" : "200"
    }, {
      "Message" : "success",
      "InstanceId" : "i-bp67acfmxazb4p****",
      "PreviousStatus" : "Running",
      "CurrentStatus" : "Stopping",
      "Code" : "200"
    }, {
      "Message" : "The specified InstanceId does not exist.",
      "InstanceId" : "i-TestID",
      "PreviousStatus" : "",
      "CurrentStatus" : "",
      "Code" : "InvalidInstanceId.NotFound"
    } ]
  }
}

Error codes

HTTP status code Error code Error message Description
400 InvalidParameter.KMSKeyId.CMKNotEnabled The CMK needs to be enabled. The error message returned because the customer master key (CMK) is not enabled when a Key Management Service (KMS) key ID is specified for a disk. You can call the DescribeKey operation of KMS to query information about the specified CMK.
400 DRYRUN.SUCCESS This request is a dryrun request with successful result. The error message returned because the validity of the request is checked and the check succeeds.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket.
403 IncorrectInstanceStatus %s The error message returned because the operation is not supported while the instance is in the current state.
403 InsufficientBalance Your account does not have enough balance. The error message returned because your Alibaba Cloud account does not have a sufficient balance. Add funds to your account and try again later.
403 InstanceNotReady The specified instance is not ready for use. The error message returned because the operation is not supported while the resource is in the current state. Try again later.
404 InvalidInstanceId.NotFound %s The error message returned because the specified instance does not exist.
404 InvalidInstanceIds.NotFound The specified InstanceIds does not exist. The error message returned because the specified InstanceId.N parameter does not exist. Check whether the InstanceId.N parameter is valid. You can call the DescribeInstances operation to query the states of specific instances.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified InstanceId.N parameter does not exist. Check whether the instance ID is correct.

For a list of error codes, visit the API Error Center.