All Products
Search
Document Center

Elastic Compute Service:ModifyPrepayInstanceSpec

Last Updated:Dec 16, 2024

Changes the instance type of a subscription Elastic Compute Service (ECS) instance. You can upgrade or downgrade the instance type. The new instance type takes effect for the entire lifecycle of the subscription ECS instance.

Operation description

Before you call this operation, make sure that you are familiar with the billing methods, prices , and rules for unsubscribing from resources of ECS.

ModifyPrepayInstanceSpec is an asynchronous operation. After a request is sent, wait for 5 to 10 seconds for the instance type change to complete. Before you change the instance type of a subscription ECS instance, call the DescribeResourcesModification operation to query the instance types to which you can change the instance.

Considerations

  • Before you change the instance type of an expired instance, you must renew the instance.

  • When you downgrade the instance type of a subscription ECS instance, take note of the following items:

    • The instance must be in the Stopped (Stopped) state.
    • The price difference is refunded to the payment account that you used. Redeemed vouchers are not refundable.
    • The new instance type takes effect only after you start the instance.
  • When you upgrade the instance type of a subscription ECS instance, take note of the following items:

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:ModifyPrepayInstanceSpecupdate
*Instance
acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
    none
none

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: The payment is automatically completed.
  • false: An order is generated but no payment is made.

Default value: true.

Note
  • Make sure that your account balance is sufficient. Otherwise, your order becomes invalid and must be canceled.

  • If your account balance is insufficient, you can set AutoPay to false to generate an unpaid order. Then, you can log on to the ECS console to pay for the order.

  • If you set OperatorType to downgrade, AutoPay is ignored.

true
MigrateAcrossZonebooleanNo

Specifies whether to allow cross-cluster instance type upgrade. Valid values:

  • true
  • false

Default value: false.

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

Instance that resides in the classic network:

  • 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 authorization codes of the instance change. For a Linux instance, basic disks (cloud) are identified as xvd* such as xvda and xvdb, and ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified as vd* such as vda and vdb.
  • For instance families available for purchase, when the instance type of an instance is changed, the private IP address of the instance changes.

Instance that resides in a virtual private cloud (VPC): 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 authorization codes of the instance change. For a Linux instance, basic disks (cloud) are identified as xvd* such as xvda and xvdb, and ultra disks (cloud_efficiency) and standard SSDs (cloud_ssd) are identified as vd* such as vda and vdb.

false
SystemDisk.CategorystringNo

The new category of the system disk. Valid values:

  • cloud_efficiency: utra disk
  • cloud_ssd: standard SSD
Note This parameter takes effect on an instance only when you change from a retired instance type to an instance type in an instance family available for purchase and upgrade the instance from a non-I/O optimized instance type to an I/O optimized instance type.
cloud_efficiency
RebootTimestringNo

The restart time of the instance. The time follows 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. The time follows 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
  • false

Default value: false.

Note If the instance is in the Stopped state, the instance remains in the Stopped state and no operations are performed, regardless of whether RebootWhenFinished is set to true.
false
ModifyModestringNo
Note This parameter is not publicly available.

Valid values:

  • Online
  • Offline
null
Diskarray<object>No
Note This parameter is not publicly available.
objectNo
DiskIdstringNo
Note This parameter is not publicly available.
null
CategorystringNo
Note This parameter is not publicly available.
null
PerformanceLevelstringNo
Note This parameter is not publicly available.
null

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.-
400InvalidSystemDiskCategory.NotMatchInstanceTypeThe system disk category does not match the instance type.-
400QuotaExceed.RufundVcpuThe maximum number of refunded vcpu is exceeded: %s .The maximum number of refund vCPUs is exceeded. For more information about the amount, see the return value of the %s placeholder in the error message.
400NoPermission.PriceThe operation requires price permission. Please either apply for permission from your main account, or set the parameter AutoPay as true.-
400NoPermission.RefundThe operation requires refund permission. Please apply for permission from your main account.-
400InvalidInstanceStatusThe current status of the instance does not support this operation.The instance is in a state that does not support the current operation.
400InvalidOperation.InstanceRenewWithDowngradeInPlanThe operation is denied due to the specified instance has renew with downgrade record in plan.There are renewal downgrade orders that have not yet taken effect. This operation is not allowed before the order takes effect.
400InvalidOperation.OnlineModificationUnsupportedOnline modification of instance type is not supported for the specified instance due to its CPU topology.-
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.
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.
403InvalidDisk.DetachedSystemDiskThe specified resource is/has a detached system disk %s , not support current operation.-
403InvalidDataDiskCategory.ValueNotSupportedThe specified Category of Data Disk is not valid.The specified data disk type is not supported.
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.
500ImageOrderFailedCreate marketplace image order failed.Failed to create the Alibaba Cloud Marketplace order. Submit a ticket.

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

Change history

Change timeSummary of changesOperation
2024-10-14The Error code has changedView Change Details
2023-12-14The Error code has changedView Change Details
2023-10-18The Error code has changedView Change Details
2023-07-28The Error code has changedView Change Details
2023-07-21The Error code has changedView Change Details
2023-06-28The Error code has changedView Change Details
2023-06-28The Error code has changedView Change Details
2023-05-08The Error code has changedView Change Details
2023-04-13The Error code has changed. The request parameters of the API has changedView Change Details
2023-04-07The Error code has changed. The request parameters of the API has changedView Change Details