All Products
Search

This Product

    Virtual Private Cloud:CreateRouterInterface

    Document Center

    Virtual Private Cloud:CreateRouterInterface

    Last Updated:Aug 28, 2026

    Creates a router interface.

    Operation description

    Take note of the following limits:

    • Only one pair of connected router interfaces can exist between two routers.

    • Each router supports a maximum of five router interfaces.

    • You cannot create router interfaces if your account has overdue payments for existing router interfaces.

    • Each destination CIDR block of route entries in the same route table must be unique.

    • A virtual border router (VBR) can serve only as a requester. The VBR must be in the Activated state.

    • Both subscription and pay-as-you-go billing methods are supported.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    No authorization for this operation. If you encounter issues with this operation, contact technical support.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The ID of the region to which the router interface belongs.

    Call DescribeRegions to query available region IDs.

    cn-hangzhou
    Role

    string

    Yes

    The role of the router interface. Valid values:

    • InitiatingSide: requester

    • AcceptingSide: acceptor

    InitiatingSide
    OppositeRegionId

    string

    Yes

    The ID of the region in which the acceptor is deployed.

    cn-shanghai
    Spec

    string

    Yes

    The router interface specification and bandwidth. Valid values:

    • Mini.2: 2 Mbit/s

    • Mini.5: 5 Mbit/s

    • Small.1: 10 Mbit/s

    • Small.2: 20 Mbit/s

    • Small.5: 50 Mbit/s

    • Middle.1: 100 Mbit/s

    • Middle.2: 200 Mbit/s

    • Middle.5: 500 Mbit/s

    • Large.1: 1,000 Mbit/s

    • Large.2: 2,000 Mbit/s

    • Large.5: 5,000 Mbit/s

    • Xlarge.1: 10,000 Mbit/s

    Note

    If Role is set to AcceptingSide, set Spec to Negative. You do not need to specify the specification for an acceptor router interface.

    Mini.2
    RouterType

    string

    Yes

    The type of router associated with the router interface. Valid values:

    • VRouter

    • VBR

    VRouter
    RouterId

    string

    Yes

    The ID of the router associated with the router interface.

    vbr-m5ebm6g9ptc9mly1c****
    OppositeInterfaceId

    string

    No

    The ID of the peer router interface.

    ri-2zeo3xzyf38r4urzd****
    OppositeRouterId

    string

    No

    The ID of the peer router.

    vrt-bp1lhl0taikrteen8****
    OppositeRouterType

    string

    No

    The type of router associated with the peer router interface. Valid values:

    • VRouter

    • VBR

    VRouter
    OppositeInterfaceOwnerId

    string

    No

    The ID of the Alibaba Cloud account to which the peer router interface belongs.

    253460731706911258
    HealthCheckSourceIp

    string

    No

    The source IP address for health checks. Must be an idle IP address in the local VPC.

    Note

    You can set this parameter when an Express Connect circuit is used.

    192.168.0.6
    HealthCheckTargetIp

    string

    No

    The destination IP address for health checks.

    Note

    This parameter is required if you specify HealthCheckSourceIp

    192.168.0.8
    AccessPointId

    string

    No

    The ID of the access point to which the VBR belongs.

    Call DescribeAccessPoints to query available access point IDs.

    Note

    This parameter is required if the VBR is connected to an Express Connect circuit.

    ap-cn-hangzhou-yh-ts-A
    OppositeAccessPointId

    string

    No

    The ID of the access point to which the peer belongs.

    Note

    Required if the peer router interface is associated with a VBR. This value cannot be changed after creation.

    ap-cn-shanghai-nt-aligroup-C
    Description

    string

    No

    The description of the router interface.

    Must be 2 to 256 characters in length, starting with a letter. Cannot start with http:// or https://.

    abcabc
    Name

    string

    No

    The name of the router interface.

    Must be 2 to 128 characters in length. Can contain letters, digits, periods (.), underscores (_), and hyphens (-).

    abc
    Period

    integer

    No

    The subscription duration. Valid values:

    • Valid values when PricingCycle is set to Month: 1 to 9.

    • Valid values when PricingCycle is set to Year: 1 to 3.

    Note

    This parameter is required if InstanceChargeType is set to PrePaid.

    3
    InstanceChargeType

    string

    No

    The billing method of the router interface. Valid values:

    • PrePaid: subscription

    • PostPaid: pay-as-you-go

    PrePaid
    AutoPay

    boolean

    No

    Specifies whether to enable automatic payment. Valid values:

    • false (default): Automatic payment is disabled. You must complete the payment in the Order Center after an order is generated.

    • true: Automatic payment is enabled. The order is paid automatically.

    Note

    This parameter is required if InstanceChargeType is set to PrePaid.

    false
    PricingCycle

    string

    No

    The billing cycle of the subscription. Valid values:

    • Month (default)

    • Year

    Note

    This parameter is required if InstanceChargeType is set to PrePaid.

    Month
    ClientToken

    string

    No

    The client token that ensures the idempotence of the request.

    You can use the client to generate the token, but it must be unique among requests.

    Note

    If you do not specify this parameter, the system uses the request ID as the client token. The request ID may differ for each request.

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

    string

    No

    The client token that ensures the idempotence of the request.

    You can use the client to generate the token, but it must be unique among requests.

    Note

    If you do not specify this parameter, the system uses the request ID as the client token. The request ID may differ for each request.

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

    boolean

    No

    Specifies whether to uplink a Fast Link mode VBR to the router interface. Fast Link mode automatically connects router interfaces between the VBR and its peer VPC. Valid values:

    • true

    • false

    Note

    • This parameter takes effect only if RouterType is set to VBR and OppositeRouterType is set to VRouter.

    • If FastLinkMode is set to true, Role must be set to InitiatingSide. In this case, AccessPointId, OppositeRouterType, OpppsiteRouterId, and OppositeInterfaceOwnerId are required.

    false
    AutoRenew

    boolean

    No

    Specifies whether to enable auto-renewal. Valid values:

    • false (default)

    • true

    false
    ResourceGroupId

    string

    No

    The ID of the resource group. What is Resource Management?

    rg-acfmxazb4ph6aiy****
    Tags

    array<object>

    No

    The tag to add to the resource.

    object

    No

    Key

    string

    No

    The tag key. You must enter at least one tag key and can specify up to 20. The tag key cannot be an empty string.

    Maximum length: 128 characters. Cannot start with aliyun or acs:, and cannot contain http:// or https://.

    FinanceDept
    Value

    string

    No

    The tag value. You can specify up to 20 tag values. The tag value can be an empty string.

    Maximum length: 128 characters. Cannot start with acs: or aliyun. Cannot contain http:// or https://.

    FinanceJoshua

    Response elements

    Element

    Type

    Description

    Example

    object

    The request ID.

    RequestId

    string

    The request ID.

    079874CD-AEC1-43E6-AC03-ADD96B6E4907
    OrderId

    integer

    The order number. This parameter is returned if InstanceChargeType is set to PrePaid.

    20210101123456
    RouterInterfaceId

    string

    The ID of the router interface.

    ri-2ze7fbuohm****

    Examples

    Success response

    JSON format

    {
  "RequestId": "079874CD-AEC1-43E6-AC03-ADD96B6E4907",
  "OrderId": 20210101123456,
  "RouterInterfaceId": "ri-2ze7fbuohm****"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidPrice.NotFound Pricing plan result not found. The Price parameter is set to an invalid value.
    400 InvalidAliuid Invalid Aliuid. The Aliuid parameter is set to an invalid value.
    400 InvalidRole.ValueNotSupported The specified Role is not valid.
    400 InvalidSpec.ValudNotSupported The specified Spec is not supported.
    400 InvalidRouterType.ValueNotSupported The specified RouterType is not valid.
    400 InvalidName.Malformed The specified "Name" is not valid.
    400 Forbidden.BillsOutstanding You cannot create more RouterInterface because you have bills outstanding.
    400 LimitationExceed.InterfaceNumberOnRouter Total number of RouterInterfaces on a Router exceeded.
    400 Forbidden.NotInRouterInterfaceCreateWhitelist Not in router interface create whitelist.
    400 RI_CREATE_ONE_LIMIT_BY_SYNC Create ri only one limit by sync.
    400 InvalidAccessPoint.ValueNotAllowed The non-vbr router interface cannot have access point configured.
    400 InvalidParam.NotFound Parameter must not be null,uid, bid,regionNo, remoteRegionNo, routerId or accessPointId The parameter value cannot be null.
    400 InvalidAccessPoint.NotMatch The accessPoint id is not matched
    400 InvalidAccessPoint.NotExist The accessPoint not exit
    400 INVAID_VBR_STATUS VBR status must be active
    400 IncorrectStatus.CenStatus Cen status must not be middle status. Check the status of the CEN instance.
    400 Forbidden.AcceptRoleNotSupportPrePay Acception side ri not support chargetype for prepaid. The subscription billing method is not supported.
    400 InvalidRouterInterfaceSpec.Malformed Specified RouterInterface spec is not valid. The RouterInterface Spec parameter is set to an invalid value.
    400 VpcSubnet.NotFound Vpc subnet not exist. The VPC subnet does not exist.
    400 IllegalParam.HealthcheckIp Healthcheck ip cannot equal with instance ip. The IP address configured for health checks cannot be the same as the IP address of the instance.
    400 OperationFailed.HcForInvalidRiType Healthchecksourceip and healthchecktargetip is only valid for vr ri that is connected to vbr. The IP address configured for health checks is invalid.
    400 OperationFailed.SyncOrderToSub SyncOrderToSub error. The operation failed.
    400 IllegalParam.CrossBorderBandwidth CrossBorder bandwidth error. The inter-region bandwidth plan is invalid.
    400 IllegalParam.VRouterType The VRouterType is not supported. The VRouterType parameter is set to an invalid value.
    400 IllegalParam.Spec The spec is illegal. The spec parameter is set to an invalid value.
    400 Forbidden.CrossBorder User not authorized to create cross border routerInterface. You do not have the permissions to create a cross-border router interface.
    400 InvalidRouterId.NotFound Param is not valid,this user does not have this router or aliuid bid regionNo and routerId must have something wrong. The RouterId parameter is set to an invalid value.
    400 InvalidCommodity.NotFound Commodity is not exist. The Commodity parameter is set to an invalid value.
    400 InvalidRouterInterfaceChargeType.Malformed Specified RouterInterface ChargeType is not valid. The RouterInterface ChargeType parameter is set to an invalid value.
    400 IllegalParam.RegionId The specified regionId is illegal. The regionId parameter is set to an invalid value.
    400 PAY.MAYI_WITHHOLDING_AGREEMENT_ILLEGAL User withhoding argeement is illegal.
    400 QuotaExceeded RiPerUser quota exceeded
    400 OperationFailed.PconnTrafficNotEnable The operation is failed because of PconnTrafficNotEnable. Billing for outbound data transfer is disabled.
    400 InvalidRegionId.NotFound The regionId provided does not exist in ec region list.
    400 ResourceNotInResourceGroup The specified resource is not in the specified ResourceGroup. The specified resource does not belong to the resource group.
    400 HaveConnectionBetweenRouters Have connection between routers A connection is established between the two routers.
    400 InvalidDescription.Malformed The specified "Description" is not valid. The description can be 2 to 256 characters in length and cannot start with http:// and https.
    400 InvalidBandwidth.NotEnough Bandwidth not enough. The bandwidth plan has insufficient bandwidth.
    400 ForbiddenAction The user does not support this action. You do not have the required permissions.
    400 OperationFailed.NotSupportIPv6 Router interface not support IPv6. The router interface does not support IPv6.
    400 InvalidParam.AvailableZoneId The specified AvailableZoneId did not retrieve the corresponding cluster IP address. The specified AvailableZoneId does not obtain the corresponding cluster IP address.
    400 OperationFailed.NoAvailableAmount The available amount of your account is less than 0, please recharge before attempting to purchase. Your account balance is negative. Top up your account before you can make a purchase.
    400 OperationFailed.OperationLocked Operation failed because OperationLocked. The operation failed because the instance is locked due to O&M.
    400 OperationFailed.InvalidEcGrant The VBR have no grant to create EC. The VBR instance is not grant by the VPC instance. Please try again after grant.
    400 OperationFailed.CannotConnectOtherOwnerInstance Can not connect with other owner VPC or CEN. Failed to bind the current resource to another account's VPC or CEN. Check whether you have the relevant permissions and try again.
    400 InvalidParams.NotNull params must not null. The parameter is required.
    404 InvalidRegionId.NotFound The regionId provided does not exist in our records. The RegionId parameter is set to an invalid value. Specify a valid value and try again.
    404 InvalidRouterId.NotFound The specified RouterId does not exist in our recored.
    404 InvalidRouterId.AttacedToCEN Can not create ri when attaced to CEN. You cannot attach the router interface to the CEN instance.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.