Throughput Reservation API Reference

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": "需要指定容量实例"
}

A successful HTTP request does not mean the capacity operation succeeded. Even when an instance write interface returns HTTP 200, output.operation_status may also be FAILED. Must check the operation status and error fields, and confirm success before using the updated capacity.

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
    }
  }
}

After the overflow strategy is enabled, traffic exceeding the capacity is billed on a pay-as-you-go basis, incurring additional fees. After it is disabled, requests exceeding the capacity will be throttled. For details on the overflow billing basis, see Throughput Reservation Billing; for more information, see Preset Throughput Long Input and Cache.

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.

After a Pay-as-you-go instance is released, purchasing a new Pay-as-you-go capacity under the same ModelCode will reuse the original instance ID. The list and details are updated to the instance information after the new purchase, and the original deletion record is no longer retained separately. The configured_capacity may be zero; the configured capacity before release is not guaranteed to be retained.

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

Query Instance details, read capability switches and the latest configuration.
Initiate a Purchase / Scaling / Renew / Delete request, Save operation_id.
If Return PROCESSING, periodically query the operation and gradually back off; if already in a terminal state, process the result directly.
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.

​Authentication and Call Preparation

​Common Conventions

​Create Throughput Reservation

​ptu_capacity

​pre_paid_info

​Create Response

​Scaling

​Query Throughput Reservation

​Query Throughput Reservation List

​Renew

​Modify Overflow Strategy

​Capacity Instance Interface

​Stack Purchase Capacity Instance

​Query Capacity Instance List (including deleted Instances)

​Query Capacity Instance Details

​Scaling a Specified Capacity Instance

​Renew specified Capacity Instance

​Delete / Release Capacity Instance

​Query Capacity Operation

​Delete Throughput Reservation

​Response Objects and Status

​Capacity Instance (CapacityInstance)

​Capacity Operation (CapacityOperation)

​Asynchronous Call, Idempotency and Error Handling

​Recommended call sequence

​Retry and Request Identifier

​Error Code

Authentication and Call Preparation

Common Conventions

Create Throughput Reservation

ptu_capacity

pre_paid_info

Create Response

Scaling

Query Throughput Reservation

Query Throughput Reservation List

Renew

Modify Overflow Strategy

Capacity Instance Interface

Stack Purchase Capacity Instance

Query Capacity Instance List (including deleted Instances)

Query Capacity Instance Details

Scaling a Specified Capacity Instance

Renew specified Capacity Instance

Delete / Release Capacity Instance

Query Capacity Operation

Delete Throughput Reservation

Response Objects and Status

Capacity Instance (CapacityInstance)

Capacity Operation (CapacityOperation)

Asynchronous Call, Idempotency and Error Handling

Recommended call sequence

Retry and Request Identifier

Error Code