You can call this operation to stop one or more ECS instances in the Running state. After the operation is successfully called, the ECS instances first enter the Stopping state, and finally enter the Stopped state.

Description

  • If the response message contains{"OperationLocks": {"LockReason" : "security"}} when you query ECS instance information, all the operations on the instances are prohibited.
  • If you enable the No Fees for Stopped Instances (VPC-Connected) feature for pay-as-you-go instances, you can set StoppedMode=KeepCharging to allow the billing to continue and retain the resources and public IP addresses for the instances that are stopped.
  • Batch operation is 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 No StopInstances

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

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

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

RegionId String Yes cn-hangzhou

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

DryRun Boolean No false

Specifies whether to check the request only. Valid values:

  • true: The request is checked, and no instance is stopped. 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 the BatchOptimization parameter to SuccessFirst and set DryRun=true, only DRYRUN.SUCCESS will be returned.
  • false: The request is checked, and the instances are stopped if the check succeeds.

Default value: false.

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: stops the instance in a normal way.

Default value: false.

StoppedMode String No KeepCharging

Specifies whether billing for the instance continues after the instance is stopped. Valid values:

  • StopCharging: Billing stops after the instance is stopped. For information about how StopCharging takes effect, see the "Prerequisites" section in No fees for stopped VPC instances.
  • KeepCharging: Billing continues after the instance is stopped.

Default value: If the prerequisites required for enabling the No Fees for Stopped Instances (VPC-Connected) feature are met and you have enabled this feature in the ECS console (For more information, see No Fees for Stopped Instances (VPC-Connected)), the default value is StopCharging. Otherwise, the default value is KeepCharging.

BatchOptimization String No AllTogether

Specifies the batch operation mode. Valid values:

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

Default value: AllTogether.

Response parameters

Parameter Type Example Description
InstanceResponses Array

The array of instance responses, which contains the status of each instance before and after the operation and the result 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.

CurrentStatus String Stopping

The current status of the instance.

InstanceId String i-bp67acfmxazb4p****

The ID of the instance.

Message String success

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

PreviousStatus String Running

The status of the instance before the operation.

RequestId String 1C488B66-B819-4D14-8711-C4EAAA13AC01

The ID of the request.

Examples

Sample requests

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

Sample success responses

XML format

<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></PreviousStatus>
                  <CurrentStatus></CurrentStatus>
                  <Code>InvalidInstanceId.NotFound</Code>
            </InstanceResponse>
      </InstanceResponses>
</StopInstancesResponse>

JSON format

{
    "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
404 InvalidInstanceId.NotFound %s The error message returned because the specified instance does not exist. Check whether the value of the InstanceId parameter is correct.
403 IncorrectInstanceStatus %s The error message returned because this operation is not supported while the instance is in the current state.
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 problem persists, submit a ticket.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified instance does not exist. Check whether the value of the InstanceId parameter is correct.
403 InsufficientBalance Your account does not have enough balance. The error message returned because your account balance is insufficient. Top up your account and try again.
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 the operation again in a few minutes.

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