All Products
Search
Document Center

Elastic Compute Service:PurchaseReservedInstancesOffering

Last Updated:Mar 19, 2024

Purchases a reserved instance. Reserved instances can be automatically matched to pay-as-you-go instances to offset the fees of the pay-as-you-go instances.

Operation description

  • Before you call this operation, make sure that you are familiar with the billing method of reserved instances. For more information, see Reserved instances.
  • Before you purchase a reserved instance, you can call the DescribeAvailableResource operation to query available instance resources.

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
RegionIdstringYes

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

cn-hangzhou
Tagobject []No

The list of tags.

KeystringNo

The key of tag N of the reserved instance. Valid values of N: 1 to 20. The tag key cannot be an empty string. The tag key can be up to 128 characters in length and cannot contain http:// or https://. It cannot start with acs: or aliyun.

TestKey
ValuestringNo

The value of tag N of the reserved instance. Valid values of N: 1 to 20. The tag value cannot be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://. It cannot start with acs: or aliyun.

TestValue
ResourceGroupIdstringNo

The ID of the resource group.

rg-bp199lyny9b3****
ZoneIdstringNo

The zone ID of the instance. This parameter is required when Scope is set to Zone. You can call the DescribeZones operation to query the most recent zone list.

cn-hangzhou-g
ReservedInstanceNamestringNo

The name of the reserved instance. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with http:// or https://. The name can contain letters, digits, colons (:), underscores (_), and hyphens (-).

testReservedInstanceName
InstanceTypestringYes

The type of the reserved instance. For more information, see Instance family.

ecs.g5.large
ScopestringNo

The scope of reserved instance N. Valid values:

  • Region: regional
  • Zone: zonal

Default value: Region.

Zone
InstanceAmountintegerNo

The number of pay-as-you-go instances of the same instance type that the reserved instance can match at the same time. Valid values: 1 to 50.

For example, if you set the InstanceAmount parameter to 3 and the InstanceType parameter to ecs.g5.large, the reserved instance can be matched three ecs.g5.large pay-as-you-go instances at the same time.

3
OfferingTypestringNo

The payment option of the reserved instance. Valid values:

  • No Upfront
  • Partial Upfront
  • All Upfront

Default value: All Upfront.

All Upfront
DescriptionstringNo

The description of the reserved instance. The description can be 2 to 256 characters in length and cannot start with http:// or https://.

This parameter is left empty by default.

testDescription
PlatformstringNo

The operating system of the image used by the instance. Valid values:

  • Windows: Windows Server operating system
  • Linux: Linux and UNIX-like operating system

Default value: Linux.

Linux
PeriodintegerNo

The validity period of the reserved instance.

Valid values: 1 and 3.

Default value: 1.

1
PeriodUnitstringNo

The unit of the validity period of the reserved instance.

Valid value: Year.

Default value: Year.

Year
ClientTokenstringNo

The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

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

Specifies whether to enable auto-renewal for the reserved instance. Default value: false. Valid values:

true: enables auto-renewal for the reserved instance. false: does not enable auto-renewal for the reserved instance.

true
AutoRenewPeriodintegerNo

The auto-renewal duration of the reserved instance. Unit: months. This parameter takes effect only when AutoRenew is set to true.

Valid values: 1, 12, 36, and 60.

Default value when PeriodUnit is set to Month: 1.

Default value when PeriodUnit is set to Year: 12.

1

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The request ID.

8C314443-AF0D-4766-9562-C83B7F1A3C8B
ReservedInstanceIdSetsarray

The IDs of the reserved instances.

string

The ID of the reserved instance.

ecsri-2ze53qonjqxg7r****

Examples

Sample success responses

JSONformat

{
  "RequestId": "8C314443-AF0D-4766-9562-C83B7F1A3C8B",
  "ReservedInstanceIdSets": {
    "ReservedInstanceId": [
      "ecsri-2ze53qonjqxg7r****"
    ]
  }
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidStartTime.ScopeNotMatchZonal reservedInstance not supported for scheduled creating.-
400InvalidInstanceType.ValueUnauthorizedThe specified InstanceType is not authorized.You are not authorized to use the specified instance type.
400InvalidDescription.MalformedThe specified parameter "Description" is not valid.The source description can be 2 to 256 characters in length. It cannot start with http:// and https://.
400InvalidParameter.ConflictThe specified region and cluster do not match.The specified region and cluster do not correspond to each other.
400InvalidTagKey.MalformedThe specified Tag.n.Key is not valid.The specified Tag.N.Key parameter is invalid.
400RegionUnauthorized%s-
400Zone.NotOnSale%sThe requested resources are unavailable in the specified zone. %s is a variable. An error message is dynamically returned based on call conditions.
400InvalidPeriodUnit.ValueNotSupportedThe specified parameter PeriodUnit is not valid.The specified PeriodUnit parameter is invalid.
400InvalidTagValue.MalformedThe specified Tag.n.Value is not valid.The specified tag value is invalid.
400InvalidChargeType.ValueNotSupportedChargeType is not valid.This billing method is not supported. Select another billing method.
400InvalidParameter.ScopeThe specified parameter 'Scope' is invalid.-
400InvalidReservedInstanceStatus.ValueNotSupportedReservedInstance status is not supported.-
400InvalidReservedInstanceOfferingType.ValueNotSupportedThe OfferingType is not supported.-
400InvalidReservedInstanceOfferingClass.ValueNotSupportedThe OfferingClass is not supported.-
400MissingParameter.ZoneIdThe specified zoneId should be not empty.-
400MissingParameter.InstanceTypeThe instanceType should be not empty.-
400MissingParameter.ReservedInstanceIdThe ids of reservedInstance can not be empty.-
400MissingParameter.ReservedInstanceConfigurationThe configurations of reservedInstance can not be empty.-
400InvalidParameter.SplitOrMergeThe Many-to-many of modification is not supported.-
400MissingParameter.InstanceTypeAndAmountBothEmptyThe instanceType and amount can not be both empty.-
400InvalidReservedInstancePlatform.ValueNotSupportedThe Platform is not supported.-
400InvalidParameter.ReservedInstanceNameReservedInstanceName is invalid.-
400InvalidReservedInstanceZone.ValueNotSupportedThe zoneId is not exist.-
400OperationDeniedThe specified InstanceType or Zone is not authorized for current user.-
400InvalidInstanceType.ValueNotSupportedThe specified InstanceType beyond the permitted range.-
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.
403OperationDeniedThe creation of Host to the specified Zone is not allowed.Dedicated hosts cannot be created in the specified zone.
403OperationDenied.NoStockThe requested resource is sold out in the specified zone; try other types of resources or other regions and zones.The requested resources are insufficient.
403OperationDeniedSales of this resource are temporarily suspended in the specified region; please try again later.The requested resource is unavailable in the specified region. Try again later.
403NodeControllerUnavailableThe Node Controller is temporarily unavailable.The node controller is unavailable.
403OperationDeniedThe resource is out of usage.The instance is not in the Running state. Start the instance or check whether the specified operation is valid.
403InvalidParameter.ResourceOwnerAccountResourceOwnerAccount is Invalid.The specified ResourceOwnerAccount parameter is invalid.
403Zone.NotOpenThe specified zone is not granted to you to buy resources yet.You are not authorized to purchase resources in the specified zone.
403Zone.NotOnSaleThe specified zone is not available for purchase.The requested resources are unavailable in the specified zone. Try a different instance type or select a different region or zone.
403InvalidResourceType.NotSupported%s-
403InvalidParameter.NotMatch%sA specified parameter is invalid. Check whether parameter conflicts exist.
403Account.ArrearageYour account has been in arrears.Your account does not have enough balance. Please add funds to your account.
404InvalidZoneId.NotFoundThe ZoneId provided does not exist in our records.The specified zone ID does not exist.
404PaymentMethodNotFoundNo payment method has been registered on the account.You have not configured a payment method for your account.
404InvalidZoneId.NotFoundThe specified ZoneId does not exist.The specified zone ID does not exist.
500InternalErrorThe request processing has failed due to some unknown error.An internal error has occurred. Try again later.
500InternalError%sAn internal error has occurred.
500InternalErrorThe request processing has failed due to some unknown error, exception or failure.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
2022-11-02The 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
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: AutoRenew
    Added Input Parameters: AutoRenewPeriod