Throughput Reservation API Reference

The Throughput Reservation (formerly TPM Reservation) API lets you create, query, and manage reserved throughput capacity. Each Throughput Reservation is identified by a ModelCode and can contain multiple capacity instances. Each instance represents a capacity purchase and can be scaled, renewed, or released separately.

Authentication and Call Preparation

Use the Bailian API Key of the calling region, and pass it in the request header Authorization: Bearer <api-key>. The API Key is bound to the region and cannot be used across regions. When the request body is JSON, pass in Content-Type: application/json.

The workspace exclusive domain format is https://{workspaceId}.{region}.maas.aliyuncs.com, use the Endpoint of the target workspace and region. If a sub-business space needs to be specified, the request header carries X-DashScope-WorkSpace: <workspace-id>.

The DashScope API domain is https://dashscope.aliyuncs.com. The Virginia region uses https://{workspaceId}.us-east-1.maas.aliyuncs.com.

The results of asynchronous capacity operations are obtained through Query Capacity Operations to obtain.

For the console entry see Throughput Reservation; for deployment concepts see Model Deployment; for general deployment APIs see Use the API for model deployment.

Common Conventions

The interface base path is /api/v1/deployments, reusing the DashScope OpenAPI domain and authentication of the calling region. The request body uses Content-Type: application/json. Use the account, model, and deployment of the target region.

• deployed_model: The calling identifier of Throughput Reservation (ModelCode); in instance/operation responses, model_service_id indicates the same object.
• instance_id: Capacity Instance ID. Use the value returned by the interface; do not infer the billing method from the string format.
• operation_id: Operation ID. Use the string value returned by the interface.
• The IDs, model names, and capacity values in the examples below are placeholders. The actual models, minimum values, step sizes, upper limits, and purchase durations are subject to the model and purchase limits of the target region.
• The JSON examples omit some optional response fields; the stage states in the examples are not fixed returns for every request.

Successful responses are uniformly wrapped as:

{
  "request_id": "example-request",
  "output": {}
}

Request error example:

{
  "request_id": "example-request",
  "code": "CAPACITY_INSTANCE_REQUIRED",
  "message": "需要指定容量实例"
}

Create Throughput Reservation

POST /api/v1/deployments

Create a Throughput Reservation and purchase the first capacity instance, returning the ModelCode used to call the model. To add capacity to an existing Throughput Reservation, please call Stack Purchase Capacity Instance.

Field	Type	Required	Description
model_name	String	Yes	Base Model Name
plan	String	Yes	ptu
service_tier	String	No	Performance Tier:ptu_fast is high speed (Default),ptu_default is standard speed
charge_type	String	Yes	pre_paid (Subscription) / post_paid (Pay-as-you-go)
name	String	No	Show name; auto-generated when not passed.
suffix	String	No	ModelCode Suffix; auto-generated when not passed.
ptu_capacity	Object	Yes	Capacity Configuration, see Capacity Parameter
pre_paid_info	Object	Conditionally Required	Subscription Required, see Subscription Parameter; Pay-as-you-go not passed

ptu_default Supports Subscription;ptu_fast Supports Subscription and Pay-as-you-go. New capacity instances inherit the ModelCode Performance Tier.

ptu_default Standard speed supports two Billing Cycles: By Day and 8 Hours period. By Day corresponds to pricing_cycle=Day, 8 Hours period corresponds to pricing_cycle=Hour And duration=8. 8 Hours period only ptu_default standard speed supports,ptu_fast high speed does not support.

By Day Subscription example:

{
  "model_name": "<base_model>",
  "plan": "ptu",
  "service_tier": "ptu_fast",
  "charge_type": "pre_paid",
  "name": "吞吐预留示例",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  }
}

8 Hours period Subscription example (only ptu_default standard speed):

{
  "model_name": "<base_model>",
  "plan": "ptu",
  "service_tier": "ptu_default",
  "charge_type": "pre_paid",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "pricing_cycle": "Hour",
    "duration": 8,
    "auto_renewal": false
  }
}

ptu_capacity

Capacity unit is kTPM (1 kTPM = 1000 Tokens/ Minutes). Currently supported models do not support separately configuring thinking output quota.

Field	Type	Description
input_tpm	Long	Input capacity, unit kTPM, provided per model requirements and satisfying step and Range
output_tpm	Long	Output capacity, unit kTPM, provided per model requirements and satisfying step and Range

When Scaling, it represents the absolute capacity after the selected Instance is changed, not the increment, nor the target total capacity of ModelCode.

pre_paid_info

Field	Type	Description
pricing_cycle	String	Billing Cycle:Day is By Day (Default),Hour is 8 Hours slots;Hour Only ptu_default Standard speed is supported and is case-sensitive
duration	Integer	Purchase / Renew duration, unit follows pricing_cycle: Day as Days, Hour as Hours and fixed at 8, must be greater than 0
auto_renewal	Boolean	Explicitly specify whether to auto-Renew;Hour scenarios must be false
auto_renewal_duration	Integer	Required when auto-renew is enabled, and must be greater than 0. The unit is Days;Hour scenario not passed
auto_renewal_cycle	String	Optional Renew billing cycle unit, pass the value supported by the product, for example Day means Day;Hour scenario not passed

Create Response

output is the Deployments object (Query Throughput Reservation). When creating a Capacity Instance, it can return operation_id, instance_id; when the purchase order of a Subscription Instance has not been fully processed, instance_id may be temporarily absent, obtain it through subsequent queries.

{
  "request_id": "example-request",
  "output": {
    "deployed_model": "example-model-code",
    "model_name": "<base_model>",
    "plan": "ptu",
    "status": "WAIT_PRE_PAID_BILLING_TO_DEPLOYING",
    "operation_id": "100001"
  }
}

When there is an operation_id, query it via Query Capacity Operation; when a creation request times out, first confirm whether it has already been created to avoid duplicate ModelCode creation.

Scaling

PUT /api/v1/deployments/{deployed_model}/scale

Adjust the input and output capacity of a capacity instance under the specified Throughput Reservation. When there are multiple undeleted instances, you must specify the target instance via instance_id.

Field	Required	Description
instance_id	Condition Required	Required when there are multiple undeleted instances; can be omitted when there is only one undeleted instance
ptu_capacity	Yes	The absolute capacity of the instance after the change
pre_paid_info	No	When Subscription is not passed, the saved information is reused; Pay-as-you-go does not pass it
order_type	No	UPGRADE is upgrade, DOWNGRADE is downgrade; when omitted, the server determines it, and the passed value must be consistent with the capacity change direction

{
  "instance_id": "example-capacity-instance",
  "ptu_capacity": {
    "input_tpm": 20000,
    "output_tpm": 2000
  },
  "order_type": "UPGRADE"
}

output Return Throughput Reservation information, the ID of the corresponding capacity operation via operation_id Return. Multiple instances without specified ID Return CAPACITY_INSTANCE_REQUIRED. New access recommended Scaling specified capacity instances.

Subscription changes involve orders, Pay-as-you-go does not go through Subscription change orders. Before the change is confirmed, the original effective capacity continues to be retained; on failure, the target capacity cannot be shown as effective. All-zero Scaling is not equivalent to deleting an instance.

Query Throughput Reservation

GET /api/v1/deployments/{deployed_model}

Query the configuration, Status, and aggregated effective capacity of all capacity instances of the specified Throughput Reservation.

{
  "request_id": "example-request",
  "output": {
    "deployed_model": "example-model-code",
    "model_name": "<base_model>",
    "plan": "ptu",
    "ptu_service_tier": "ptu_fast",
    "status": "RUNNING",
    "charge_type": "pre_paid",
    "ptu_capacity": {
      "input_tpm": 10000,
      "output_tpm": 1000
    },
    "overflow_strategy": "disable"
  }
}

Field	Description
deployed_model	The calling identifier of the Throughput Reservation (ModelCode).
model_name	Base model name.
plan	Type identifier, throughput reserved is ptu.
status	ModelCode Status, does not represent the Status of each Capacity Instance
ptu_service_tier	Performance Tier: ptu_fast for high-speed, ptu_default for standard-speed
ptu_capacity	The total input and output capacity that has taken effect for all Capacity Instances under this ModelCode
charge_type	Value: pre_paid (Subscription) / post_paid (Pay-as-you-go)
pre_paid_info	Subscription purchase and renewal configuration, including pricing_cycle (Day By Day / Hour for 8 Hours period), duration etc. When there are multiple capacity instances, please query the target instance's via instance details pre_paid_info.
pre_paid_instance_id	Subscription instance ID. When there are multiple capacity instances, please obtain each instance's via the capacity instance list instance_id, and specify the instance to operate on.
pre_paid_gmt_expired	Subscription expiration time. When there are multiple capacity instances, please via the target instance details' gmt_expired to obtain its expiration time. For expiration time calculation rules, see Throughput Reservation Billing.
overflow_strategy	Overflow strategy, enable indicates that overflow pay-as-you-go billing is allowed,disable indicates that traffic is limited when capacity is exceeded. For details on overflow billing, seeThroughput Reservation Billing.
fail_reason	Failure reason.
gmt_create	Created At.
gmt_modified	Last modified time.
operation_id	Capacity operation ID, used to query operation results; may be returned in the response of the corresponding write operation.
instance_id	Capacity instance ID. May not be returned when the purchase order has not yet been processed; please obtain it through subsequent queries.

Hybrid billing should be determined through the charge_type of each instance in the capacity instance list to determine. The Deployment status and billing type cannot replace the status and billing type of each instance.

Query Throughput Reservation List

GET /api/v1/deployments?page_no=1&page_size=10&plan=ptu

Paginated query for Throughput Reservation List.

Query Parameter	Description
page_no	Page Number, Default 1
page_size	Quantity per page, Default 10, Range [1,100]
plan	Optional type filter. Pass when querying Throughput Reservation ptu; Performance Tier is represented by service_tier and is not used as plan value

{
  "request_id": "example-request",
  "output": {
    "deployments": [
      {
        "deployed_model": "example-model-code",
        "plan": "ptu",
        "status": "RUNNING",
        "ptu_capacity": {
          "input_tpm": 10000,
          "output_tpm": 1000
        }
      }
    ],
    "total": 1,
    "page_no": 1,
    "page_size": 10
  }
}

Deploy List does not support filtering status via status parameter. For capacity instance filtering, please use Query Capacity Instance List (including deleted instances) of statuses.

Renew

PUT /api/v1/deployments/{deployed_model}/renew

Renew the specified Subscription capacity instance, and adjust the capacity at the same time. When there are multiple undeleted instances, you must use instance_id to specify the target instance.

Field	Required	Description
instance_id	Condition Required	Must be specified when there are multiple non-deleted instances; can be omitted for a single instance for compatibility
pre_paid_info	Yes	Renew information, see Subscription Parameter
is_change	No	Default false; whether to adjust capacity at the same time
ptu_capacity	No	If omitted, the configured capacity is retained; when passing a different capacity, must is_change=true

Renew and enable auto-renewal:

{
  "instance_id": "example-capacity-instance",
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": true,
    "auto_renewal_duration": 30
  }
}

Renew but do not enable auto-renewal:

{
  "instance_id": "example-capacity-instance",
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  }
}

Subscription only; Renew requests cannot pass order_type. output Return Throughput Reserved information, and may contain a Capacity Operation ID; recommend using Renew Specified Capacity Instance instance-level interface and poll results.

Modify Overflow Strategy

PUT /api/v1/deployments/{deployed_model}/update-overflowstrategy

{
  "overflow_strategy": "disable"
}

overflow_strategy Required, only supports lowercase enable / disable. enable indicates that traffic exceeding PTU capacity is allowed to overflow to the public pool and be billed by usage; disable indicates rate limiting after exceeding. The configuration applies to the entire ModelCode; capacity packs do not configure overflow strategy separately. For overflow billing details, seeThroughput Reservation Billing.

The response contains request_id and output. After modification, you can use Query Throughput Reservation to obtain overflow_strategy to confirm the configuration has been updated.

{
  "request_id": "example-request",
  "output": {
    "deployed_model": "example-model-code",
    "model_name": "<base_model>",
    "plan": "ptu_v2",
    "ptu_service_tier": "ptu_fast",
    "status": "RUNNING",
    "charge_type": "post_paid",
    "overflow_strategy": "disable",
    "ptu_capacity": {
      "input_tpm_quota": 10000,
      "output_tpm_quota": 10000
    }
  }
}

Capacity Instance Interface

The following interfaces all use /api/v1/deployments/{deployed_model} as prefix. Instance write operations return Capacity Operation operation object, different from the old /scale, /renew Deployments object.

Stack Purchase Capacity Instance

POST /api/v1/deployments/{deployed_model}/capacity-instances

Field	Required	Description
billing_method	Yes	Billing Method:PRE_PAY is Subscription,POST_PAY is Pay-as-you-go. The value is case-sensitive
ptu_capacity	Yes	New instance capacity
pre_paid_info	Conditionally Required	Required for Subscription, not passed for Pay-as-you-go

Subscription example:

{
  "billing_method": "PRE_PAY",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  }
}

8-hour period add-on purchase example (only ptu_default standard rate, billing_method fixed PRE_PAY, pre_paid_info pass pricing_cycle=Hour / duration=8 / auto_renewal=false):

{
  "billing_method": "PRE_PAY",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "pricing_cycle": "Hour",
    "duration": 8,
    "auto_renewal": false
  }
}

After the 8-hour period instance is created successfully, through Query Capacity Instance Details the following fields can be obtained: pricing_cycle is Hour; gmt_effective is the effective time at Beijing time on the hour; gmt_expired and gmt_effective differ by 8 Hours; can_scale, can_renew, can_enable_auto_renew, can_disable_auto_renew, can_delete are all false.

Pay-as-you-go example:

{
  "billing_method": "POST_PAY",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  }
}

Return the Actions object. The initial response may already be successful, Failed, or still processing. Reuse the existing ModelCode, model and Performance Tier; the same ModelCode only allows one undeleted Pay-as-you-go Instance. When Purchase conditions or Instance quantity do not meet the requirements, handle according to the error returned by the interface.

Query Capacity Instance List (including deleted Instances)

GET /api/v1/deployments/{deployed_model}/capacity-instances?page_no=1&page_size=20&include_deleted=true

Query Parameters	Type	Description
page_no	Integer	Default 1
page_size	Integer	Default 20, Range [1,100]
include_deleted	Boolean	Default true; explicitly pass false to show only undeleted instances
statuses	String List	Optional, multiple values comma-separated, e.g. RUNNING,STOPPED
charge_types	String List	Optional,pre_paid,post_paid

{
  "request_id": "example-request",
  "output": {
    "records": [
      {
        "model_service_id": "example-model-code",
        "instance_id": "example-capacity-instance",
        "charge_type": "post_paid",
        "status": "STOPPED",
        "deleted": true,
        "effective_capacity": {
          "input_tpm": 0,
          "output_tpm": 0
        },
        "configured_capacity": {
          "input_tpm": 0,
          "output_tpm": 0
        },
        "can_scale": false,
        "can_renew": false,
        "can_delete": false
      }
    ],
    "items": 1,
    "page": 1,
    "itemsPerPage": 20,
    "pageCount": 1
  }
}

Pagination structure differs from the Deploy list:records is the current page,items is the total count,page is the page number,itemsPerPage / pageCount retains the camelCase spelling of the current response. Instances with active capacity are prioritized first, then sorted by Created At in descending order. The List only supports the query parameters listed in this section.

Query Capacity Instance Details

GET /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}

Return CapacityInstance the instance object; deleted instances can also be queried. ModelCode must match the instance; cross-ModelCode operations on instances are not allowed.

Scaling a Specified Capacity Instance

PUT /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}/scale

{
  "ptu_capacity": {
    "input_tpm": 20000,
    "output_tpm": 2000
  },
  "order_type": "UPGRADE"
}

The parameter semantics are the same as Scaling; the instance ID is determined by the path, no need to repeat in the request body. Return the Actions object. Before calling, read can_scale; Subscription expired pending Instance cannot be Scaling directly, should Renew first. 8 Hours time-segment Instance does not support Scaling, Return CAPACITY_INSTANCE_OPERATION_UNSUPPORTED.

Renew specified Capacity Instance

PUT /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}/renew

Normal Renew:

{
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  }
}

Renew and adjust capacity:

{
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  },
  "is_change": true,
  "ptu_capacity": {
    "input_tpm": 20000,
    "output_tpm": 2000
  }
}

Parameter constraints same as Renew, not pass order_type. Only Subscription can Renew, check first can_renew; Return operation object. 8 Hours time-segment Instance does not support Renew and auto-renew, Return CAPACITY_INSTANCE_OPERATION_UNSUPPORTED.

Delete / Release Capacity Instance

DELETE /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}

Optional Query Parameters reason is the deletion reason, URL-encoded; no JSON request body required. Return the operation object.

• Pay-as-you-go: released via the deletion process, and upon completion deleted=true, status=STOPPED, the effective capacity is zero.
• Active Subscription: cannot use this interface to replace unsubscription; calling directly returns PREPAID_UNSUBSCRIBE_REQUIRED. After completing unsubscription and releasing capacity, ultimately returns deleted=true, status=STOPPED.
• 8-hour time-slot instances do not support direct deletion; calling returns PREPAID_UNSUBSCRIBE_REQUIRED, the commercial unsubscription process must be followed.
• can_delete=true indicates the current status allows entering the deletion / unsubscription process, but does not indicate that prepaid can skip unsubscription and directly DELETE. For failed instances without an associated order yet, handle them according to the interface return result.

Unsubscription release is an asynchronous operation. When the same ModelCode is processing other operations, the accepted release operation will queue and wait; before completion, queries may still return the original status and effective capacity. Unsubscription accepted does not mean capacity is released; please verify through the operation result and the instance deleted Field confirmation complete. For unsubscribe and refund formula details seeThroughput Reserved Billing.

Query Capacity Operation

GET /api/v1/deployments/{deployed_model}/capacity-operations/{operation_id}

{
  "request_id": "example-poll-request",
  "output": {
    "operation_id": "100001",
    "request_id": "example-original-request",
    "operation_type": "SCALE",
    "operation_status": "SUCCEEDED",
    "model_service_id": "example-model-code",
    "instance_id": "example-capacity-instance",
    "from_status": "RUNNING",
    "current_status": "RUNNING"
  }
}

Outer request_id is the request identifier for this query, and the one inside the operation object request_id is the original operation identifier; the two may differ. The query path must belong to the ModelCode that created the operation.

Use the one actually returned by the write operation operation_id, do not construct it yourself. When querying a non-existent numeric ID or operations of another ModelCode, HTTP 404 is returned, CAPACITY_OPERATION_NOT_FOUND; when an invalid ID containing non-numeric characters such as letters is passed in, HTTP 500 may be returned, InternalError. When encountering this error, first verify the ID; do not directly repeat capacity write operations.

Delete Throughput Reservation

DELETE /api/v1/deployments/{deployed_model}

Need to first release all Capacity Instances, And ModelCode is STOPPED, with no Capacity Operation in progress or queued, then Delete the entire Deploy. Return the Deploy object.

After the last Instance is released, ModelCode changes to STOPPED, and ModelCode will not be automatically deleted as a result. Deleting a Capacity Instance and deleting ModelCode are two different Actions.

Response Objects and Status

Capacity Instance (CapacityInstance)

Field	Type	Description
model_service_id	String	The ModelCode to which the CapacityInstance or operation belongs.
instance_id	String	CapacityInstance ID.
charge_type	String	pre_paid(Subscription) / post_paid(Pay-as-you-go)
status	String	Instance lifecycle status, see the table below
deleted	Boolean	Whether it has been deleted / released, used to identify Released instances
effective_capacity	Object	The capacity currently confirmed to provide service
configured_capacity	Object	Instance configuration / contracted capacity; still retained when Stopped or Suspended
target_capacity	Object	The target capacity being changed to, may not be returned or be empty in a stable state
pre_paid_info	Object	The Subscription purchase and Renew configuration of this instance, including pricing_cycle (Day By Day / Hour for 8 Hours time slot), see Subscription Parameter.
gmt_effective	String	Subscription Instance effective time; 8 Hours time slot Instance takes effect on the hour in Beijing time. Parse by timezone offset, do not take the +00:00 's hour number directly as Beijing time.
gmt_expired	String	Subscription Instance expiration time; 8 Hours time slot Instance and gmt_effective differ by 8 Hours. Expiration time calculation rule see Throughput Reserved Billing.
can_scale	Boolean	Whether Scaling is currently allowed for the Instance; 8 Hours time slot Instance fixed false.
can_renew	Boolean	Whether Renew is currently allowed for the Instance; 8 Hours time slot Instance fixed false.
can_enable_auto_renew	Boolean	Whether auto-renewal is currently allowed to be enabled; fixed for 8-hour time-slot instances false.
can_disable_auto_renew	Boolean	Whether auto-renewal is currently allowed to be disabled; fixed for 8-hour time-slot instances false.
can_delete	Boolean	Whether deleting or unsubscribing an instance is currently allowed; Subscription instances still need to complete the unsubscribe process, fixed for 8-hour time-slot instances false.
fail_reason	String	Failure reason
gmt_created	Time	Created At.
gmt_modified	Time	Last modified time.
gmt_deleted	Time	Deletion time.

Status	Meaning and Display Suggestions
WAIT_PRE_PAID_BILLING_TO_DEPLOYING / WAIT_TO_DEPLOY	Waiting for purchase processing / Waiting to take effect
RUNNING	Running
WAIT_PRE_PAID_BILLING_TO_SCALING / SCALING	Waiting for update order / Updating
STOPPING / STOPPED	Stopping / Stopped; combined with deleted to distinguish Released
SUSPENDING / SUSPENDED	Suspending / Suspended
STARTING / RECOVERING	Starting / Resuming
DELETING	Deleting
FAILED	Failed, handle based on the failure reason

Pay-as-you-go deletion and Subscription refund can be uniformly shown as "Released" under the condition deleted=true, rather than only status=STOPPED. STOPPED + deleted=false still being a reserved instance. deleted=true instances do not allow scaling, renew, or delete.

RUNNING status does not mean all actions are available. When the same ModelCode has an in-progress action or billing restrictions, the corresponding action may be unavailable. Subscription SUSPENDED instances cannot be scaled; can be renewed when meeting renewal conditions; Pay-as-you-go instances cannot be renewed. Re-query the instance details before calling, check whether the action is available through can_scale, can_renew, can_delete, and handle errors returned by the interface.

Capacity Operation (CapacityOperation)

Field	Description
operation_id	Capacity Operation ID, used to query operation results; may be returned in the corresponding write operation response.
request_id	Request identifier for initiating this capacity operation.
operation_type	Common CREATE, SCALE, RENEW, DELETE; lifecycle handling may also show STOP, REFUND, does not imply that a public write interface with the same name exists
operation_status	Value: PROCESSING, SUCCEEDED, FAILED
model_service_id	ModelCode to which the capacity instance or operation belongs.
instance_id	Capacity Instance ID. May not be returned when the purchase order has not been fully processed; please Obtain it through subsequent queries.
from_status	Instance status before the operation.
current_status	Instance current status.
error_code	Error Code returned when the operation fails.
error_message	Error Description returned when the operation fails.
gmt_created	Created At.
gmt_finished	Operation completion Time.

When the operation is being executed or queued, Return PROCESSING. SUCCEEDED / FAILED is the terminal Status, stop polling after receiving the terminal Status, and refresh the Instance and Deploy summary.

Asynchronous Call, Idempotency and Error Handling

Recommended call sequence

1. Query Instance details, read capability switches and the latest configuration.
2. Initiate a Purchase / Scaling / Renew / Delete request, Save operation_id.
3. If Return PROCESSING, periodically query the operation and gradually back off; if already in a terminal state, process the result directly.
4. SUCCEEDED then refresh the Instance and ModelCode; FAILED Show error_code / error_message. Network timeout does not equal Actions failure; check existing Actions first.

Capacity changes for the same ModelCode are processed in order; when there are in-progress Actions, new changes may be rejected. Accepted cancellation-release Actions are queued and continue after preceding Actions complete. Before the change takes effect, queries still Return the original effective capacity; the target capacity should not be considered as effective.

After stacking, Scaling, or release takes effect, you can Obtain the updated aggregate effective capacity through the Deploy query interface and continue using the original ModelCode. Calling the model also requires completing the corresponding Deployments, and using correct Account authentication and call parameters; capacity Actions success does not mean all other conditions for model calling are met.

Retry and Request Identifier

For network retries of the same capacity write Actions, keep the request identifier and parameters unchanged. It is recommended to x-acs-req-uuid and X-DashScope-RequestId set to the same UUID to avoid inconsistency between the two causing actual identifier changes. The current read priority is x-acs-req-uuid, X-DashScope-RequestId, X-Request-Id, when neither is provided, a new identifier is generated.

Capacity operations with the same ModelCode, the same valid request identifier, and the same operation parameters reuse existing operations; changing parameters with the same identifier will return IDEMPOTENCY_KEY_CONFLICT. New business operations use new identifiers. Do not directly apply this instance operation idempotency convention to the first creation of ModelCode.

Error Code

Error Code	HTTP	Handling Suggestion
CAPACITY_INSTANCE_REQUIRED	400	When multiple instances exist, specify the target instance_id
CAPACITY_INSTANCE_OPERATION_UNSUPPORTED	400	Refresh details and capability switches, confirm the current status and billing method support the operation
PREPAID_UNSUBSCRIBE_REQUIRED	400	Enter the existing unsubscription process
POSTPAID_INSTANCE_ALREADY_EXISTS	400	Reuse the existing pay-as-you-go instance, or release it before creating a new one
CAPACITY_SLOT_LIMIT_EXCEEDED / TOTAL_CAPACITY_INSTANCE_LIMIT_EXCEEDED	400	Reached the active instance slot limit / total count limit including historical records
MODEL_CODE_DELETED	400	Do not initiate write operations on a deleted Throughput Reservation
MODEL_CODE_NOT_FOUND / CAPACITY_INSTANCE_NOT_FOUND	404	Check the region, account, ModelCode, and instance ownership; scaling a deleted instance may also return CAPACITY_INSTANCE_NOT_FOUND
CAPACITY_OPERATION_NOT_FOUND	404	The operation does not exist or does not belong to the specified ModelCode. Verify the ID returned by the write operation.
InternalError	500	May be returned when the operation query passes an invalid non-numeric ID; verify the ID first, and for other internal errors retain the request_id and contact technical support.
CAPACITY_INSTANCE_OPERATION_CONFLICT	409	Query existing operations first, and initiate a new operation after the previous one is completed.
IDEMPOTENCY_KEY_CONFLICT	409	Keep the original parameters for retries; use a new identifier for different business operations.
BILLING_ACCOUNT_NOT_READY	403	Check whether the Account meets the Purchase conditions.
BILLING_SERVICE_UNAVAILABLE	503	Query existing operations and handle retries with backoff strategy

HTTP in the table corresponds to errors thrown at the request phase; asynchronous operation failures are returned through the error field of the operation object, so you cannot judge solely by HTTP status.

Other general errors:

HTTP Status Code	Error Code	Handling Suggestion
400	InvalidParameter	Verify the parameter name, type, capacity change direction, and value.
401	InvalidApiKey	Check the validity and region of the API Key.
403	AccessDenied / Model.AccessDenied / App.AccessDenied	Check account permissions, workspace, and model authorization.
404	ModelNotFound	Verify the base model name and supported range.
409	Conflict	Deploy name duplicate, change name or suffix.
429	Throttling / Throttling.RateQuota / Throttling.AllocationQuota	Throughput Reserved excess corresponds to AllocationQuota, can scale or adjust overflow strategy.
500	RequestTimeOut	First check existing operations to avoid duplicate Purchase; keep request_id to contact technical support.
503	ModelUnavailable	Retry later or switch to an available model.

For rate limit handling seeBest practices for rate limit handling.