All Products
Search
Document Center

Elastic Compute Service:ModifyPrepayInstanceSpec

Last Updated:Feb 04, 2024

Upgrades or downgrades the instance type of a subscription instance. The new instance type takes effect for the remaining lifecycle of the instance.

Operation description

Before you call this operation, we recommend that you familiarize yourself with the billing methods, pricing schedule, and refund rules of ECS . For more information, see Refund rules for real-time configuration downgrade.

Before you change the instance type of a subscription instance, you can call the DescribeResourcesModification operation to query the instance types to which you can change the instance. You can use ECS SDK for Python to query the instance types to which you can change. For more information, see Query available resources for configuration changes.

When you call this operation, take note of the following items:

  • You cannot change the instance type of an expired instance. Renew the instance and try again.

  • When you downgrade the instance type of an instance, take note of the following items:

    • The instance must be in the Stopped state.****
    • You must specify the operation type by setting OperatorType to downgrade.
    • You can downgrade the configurations of an instance up to three times. Therefore, up to three refunds for the price difference can be made for an instance. Downgrade operations include instance type downgrades, bandwidth configuration downgrades, and the change of the disk billing method from subscription to pay-as-you-go.
    • The price difference is refunded to the payment account you used. Vouchers that have been redeemed during purchase are not refundable.
  • This operation is asynchronous. It takes 5 to 10 seconds for the instance type to change. You must restart the instance by calling the RebootInstance operation or by using the ECS console for the instance type change to take effect. If you restart only the operating system of the instance, the instance type change does not take effect.

    • If the instance is in the Stopped state, you only need to start the instance. You do not need to restart the instance after it enters the Running state.
    • If RebootWhenFinished is set to true for the instance, you do not need to manually restart the instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
InstanceIdstringYes

The instance ID.

i-bp67acfmxazb4ph****
RegionIdstringYes

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

cn-hangzhou
InstanceTypestringYes

The new instance type. For information about available instance types, see Instance families or call the DescribeInstanceTypes operation.

ecs.g5.xlarge
OperatorTypestringNo

The type of the change to the instance. Valid values:

Note This parameter is optional. The system can automatically determine whether the instance change is an upgrade or a downgrade. If you want to specify this parameter, refer to the following valid values of the parameter.
  • upgrade: upgrades the instance type. Make sure that the balance in your account is sufficient.
  • downgrade: downgrades the instance type. When the new instance type specified by the InstanceType parameter has lower specifications than the current instance type, set OperatorType to downgrade.
Note You can refer to the preceding usage notes on how to upgrade or downgrade the instance type.
upgrade
ClientTokenstringNo

The client token that you want to use to ensure the idempotency of the request. You can use the client to generate the value, but make sure that the value is unique among different requests. This value allows only ASCII characters and is up to 64 characters in length. For more information, see How do I ensure the idempotence of a request?

123e4567-e89b-12d3-a456-426655440000
AutoPaybooleanNo

Specifies whether to enable automatic payment when you upgrade the instance type. Valid values:

  • true: enables automatic payment.

    **

    Make sure that your payment account has sufficient balance. Otherwise, your order becomes invalid and is canceled. If your account balance is insufficient, you can set the AutoPay parameter to false to generate an unpaid order. Then, you can log on to the ECS console to pay for the order.````

  • false: An order is generated but no payment is made.

Default value: true.

When OperatorType is set to downgrade, AutoPay is ignored.

true
MigrateAcrossZonebooleanNo

Specifies whether to support cross-cluster instance type upgrades.

Default value: false.

When you set MigrateAcrossZone to true and you upgrade the instance based on the returned information, take note of the following items:

Instances of the classic network type:

  • For retired instance types, when a non-I/O optimized instance is upgraded to an I/O optimized instance, the private IP address, disk device names, and software license codes of the instance are changed. For more information, see Retired instance types. For Linux instances, basic disks (cloud) are identified by the prefix xvd. Ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified by the prefix vd.
  • For instance families available for purchase, when the instance type of an instance is changed, the private IP address of the instance changes.

Instances of the Virtual Private Cloud (VPC) type: For retired instance types, when a non-I/O optimized instance is upgraded to an I/O optimized instance, the disk device names and software license codes of the instance are changed. For Linux instances, basic disks (cloud) are identified by the prefix xvd. Ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified by the prefix vd.

false
SystemDisk.CategorystringNo

The new category of the system disk. This parameter is applicable only when you upgrade an instance from a retired instance type to a currently available instance type or when you upgrade a non-I/O optimized instance to an I/O optimized instance. For more information, see Retired instance types and Instance families. Valid values:

  • cloud_efficiency: ultra disk.
  • cloud_ssd: standard SSD.
cloud_efficiency
RebootTimestringNo

The restart time of the instance. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

2018-01-01T12:05Z
EndTimestringNo

The end time of the temporary change. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

2018-01-01T12:05Z
RebootWhenFinishedbooleanNo

Specifies whether to restart the instance immediately after the instance type is changed. Valid values:

  • true: restart the instance immediately after the instance type is changed.
  • false: does not restart the instance immediately after the instance type is changed.

Default value: false.

Note If the instance is in the Stopping state, the instance status remains unchanged and no operations are performed after the instance type is change regardless of whether you set the RebootWhenFinished parameter to true.
false

Response parameters

ParameterTypeDescriptionExample
object
OrderIdstring

The ID of the order.

1234567890
RequestIdstring

The ID of the request.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

Examples

Sample success responses

JSONformat

{
  "OrderId": "1234567890",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidInstanceType.ValueUnauthorizedThe specified InstanceType is not authorized.You are not authorized to use the specified instance type.
400InvalidInstanceType.ValueNotSupportedThe specified InstanceType does not exist or beyond the permitted range.The specified instance type does not exist or you are not authorized to manage instances of this instance type.
400InvalidBillingMethod.ValueNotSupportedThe operation is not permitted due to an invalid billing method of the instance.The operation is not supported due to the invalid instance billing method.
400InvalidInstance.PurchaseNotFoundThe specified instance has no purchase history.The order record for the instance does not exist.
400InvalidInstance.UnpaidOrderThe specified instance has unpaid order.The specified instance has a purchase order not paid for.
400InvalidInstanceType.NotSupportedThe specified InstanceType is not Supported.The specified InstanceType parameter is invalid.
400OrderCreationFailedOrder creation failed, please check your params and try it again later.-
400ThrottlingYou have made too many requests within a short time; your request is denied due to request throttling.-
400Account.ArrearageYour account has an outstanding payment.Your account has overdue payments.
400InvalidInstanceId.NotFoundThe specified InstanceId does not exist.The specified instance does not exist.
400InvalidRebootTime.MalFormedThe specified rebootTime is not valid.The specified RebootTime parameter is invalid.
400InvalidRebootTime.ValueNotSupportedThe specified RebootTime is not valid.The specified RebootTime is invalid.
400IdempotenceParamNotMatchRequest uses a client token in a previous request but is not identical to that request.This request and the previous request contain the same client token but different other parameters.
400IdempotenceParamNotMatch%sThe idempotent parameters do not match.
400InvalidInstanceChargeType.ValueNotSupported%sThe specified InstanceChargeType parameter is invalid.
400InvalidStatus.NotStoppedInstance status must be stopped.-
400InvalidAction%sThe operation is invalid.
400InstanceDowngrade.QuotaExceedQuota of instance downgrade is exceed.The maximum number of configuration downgrades allowed for the instance has been reached.
400InvalidInstanceType.ValueNotSupported%sThe operation is not supported by the specified instance type.
400InvalidParameter%sThe specified parameter is invalid.
400OperationDeniedThe current user does not support this operation.Your account does not support this operation.
400LastOrderProcessingThe previous order is still processing, please try again later.The order is being processed. Try again later.
400InvalidOperation.VpcHasEnabledAdvancedNetworkFeatureThe specified vpc has enabled advanced network feature.Advanced features are enabled for the specified VPC. You cannot create low-specification instances in the VPC.
400InvalidAction.WithActiveElasticUpgradeThe instance has active Elastic Upgrade.The operation is not supported while the instance are being temporarily upgraded. The instance goes through a temporary configuration upgrade if the EndTime parameter is specified to call the ModifyPrepayInstanceSpec operation.
400InstanceTypeNotSupported.TooManyDisksAttached%s-
400QuotaExceed.DiskCapacityThe used capacity of disk type has exceeded the quota in the zone, %s.The capacity of disks that belong to the specified disk category exceeds the quota limit for the zone.
400MissingParameter.DiskCategoryThe specified parameter Disk.Category can not be null when Disk.DiskId is specified.-
400InvalidParameter.DiskCategoryThe specified parameter Disk.Category is not valid.-
400InvalidPerformanceLevel.MalformedThe specified parameter Disk.n.PerformanceLevel is not valid.-
403OperationDenied.NoStockThe specified instance is out of usage.The resources of the specified instance type are insufficient.
403InvalidUser.PassRoleForbiddenThe RAM user does not have privilege to pass a role.RAM users are not authorized to assign RAM roles.
403ImageNotSupportInstanceTypeThe specified image does not support the specified InstanceType.The specified image does not support the specified instance type.
403InstanceType.Offline%sThe operation is not supported while the instance type is retired or while resources of the instance type are insufficient.
403IncorrectInstanceStatusThe current status of the resource does not support this operation.The resource is in a state that does not support the current operation.
403InvalidParameter.InstanceId%sThe specified InstanceId parameter is invalid.
403OperationDenied%sThe operation is denied.
403ImageNotSupportInstanceTypeThe specified instanceType is not supported by instance with marketplace image.The specified Alibaba Cloud Marketplace image does not support the instance type.
403InvalidInstanceStatusThe current status of the instance does not support this operation.The instance is in a state that does not support the current operation.
403InvalidOperation.StarterPackageStarterPackage not support modification.-
403InvalidInstance.PreInstanceExpiredInstance business status is not Expired.-
403InvalidInstance.EipNotSupportThe special instance with eip not support operate, please unassociate eip first.The operation is not supported while an EIP is associated with the instance. Disassociate the EIP first.
403OperationDenied.ImageNotValidThe specified image is not authorized.You are not authorized to use this image.
403OperationDenied.LocalDiskUnsupportedThe configuration change is not allowed when the specified instance has local disks mounted.Instance types cannot be changed for instances that have local disks attached.
403OperationDenied.NoStockThe resource is out of stock in the specified zone. Please try other types, or choose other regions and zones.The requested resources are unavailable in the specified zone. Try a different resource type or select a different region or zone.
403InvalidOperation.EniCountExceeded%s-
403InvalidOperation.Ipv4CountExceeded%sThe operation is valid because the maximum number of IPv4 addresses has been reached.
403InvalidOperation.Ipv6CountExceeded%sThe operation is valid because the maximum number of IPv6 addresses has been reached.
403InvalidOperation.Ipv6NotSupport%s-
403InvalidOperation.Ipv4NotSupport%s-
403InvalidInstance.NotFoundSystemDiskThe specified instance has no system disk.The specified instance does not have a system disk. Make sure that the instance has a system disk. You can call the DescribeInstances operation to query the details of the instance.
403InvalidInstanceType.NotSupportDiskCategoryThe instanceType of the specified instance does not support this disk category.The instance type does not support the current disk category. Try another instance type. For information about the disk categories supported by instance types, see the instance family documentation.
403QuotaExceed.ElasticQuotaNo additional quota is available for the specified ECS instance type.The maximum number of instances of the specified instance type in the region has been reached. Reduce the quantity of instances that you want to purchase or try another region or instance type. Alternatively, you can go to the ECS console or Quota Center to request a quota increase.
403QuotaExceed.ElasticQuotaThe number of the specified ECS instances has exceeded the quota of the specified instance type.The maximum number of instances of the specified instance type in the region has been reached. Reduce the quantity of instances that you want to purchase or try another region or instance type. Alternatively, you can go to the ECS console or Quota Center to request a quota increase.
403QuotaExceed.ElasticQuotaThe number of vCPUs assigned to the ECS instances has exceeded the quota in the zone.The maximum number of vCPUs for all instance types has been reached. You can go to the ECS console or Quota Center to request a quota increase.
403QuotaExceed.ElasticQuotaThe number of the specified ECS instances has exceeded the quota of the specified instance type, or the number of vCPUs assigned to the ECS instances has exceeded the quota in the zone.The maximum number of instances of the specified instance type in the region has been reached, or the maximum number of vCPUs for all instance types has been reached. You can go to the ECS console or Quota Center to request a quota increase.
403InvalidResourceType.NotSupported%s-
403InvalidOperation.MaxEniQueueNumberExceeded%s-
403InvalidOperation.ExceedInstanceTypeQueueNumber%sThe maximum number of queues for all ENIs on an instance has been exceeded. For more information, see the return value of the %s placeholder in the error message.
403InvalidParameter.InvalidEniQueueNumber%s-
403HibernationConfigured.InstanceOperationForbiddenThe operation is not permitted due to limit of the hibernation configured instance.The operation cannot be performed due to the limitations of instances for which the instance hibernation feature is enabled.
403InvalidOperation.MaxModifyOnlineNumberExceededThe specified instance has reached the maximum number of modify online attempts and needs to be rebooted.-
403InvalidOperation.RebootingRequiredThe specified instance needs to be rebooted.-
403InvalidOperation.OSTypeNotSupportedThe specified OS type is not supported.-
403OperationDenied.UnpaidOrderThe specified instance has unpaid order.Your account has unpaid orders for the specified instance. You can log on to the ECS console to pay for the orders.
404InvalidRegionId.NotFoundThe specified RegionId does not exist.The specified region ID does not exist.
404BillingMethodNotFoundThe account has not chosen any billing method.No billing method is selected for the Alibaba Cloud account.
500InternalErrorThe request processing has failed due to some unknown error, exception or failure.An internal error has occurred. Try again later.
500InternalErrorThe request processing has failed due to some unknown error.An internal error has occurred. Try again later.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2023-12-14The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
2023-10-18The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
2023-07-28The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 500 change
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 404
2023-07-21The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
2023-06-28The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
2023-06-28The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
2023-05-08The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
2023-04-13The Error code has changed. The request parameters of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    Error Codes 403 change
    delete Error Codes: 404
    delete Error Codes: 500
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: Disk
2023-04-07The Error code has changed. The request parameters of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 403 change
    delete Error Codes: 400
    delete Error Codes: 404
    delete Error Codes: 500
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: ModifyMode