All Products
Search
Document Center

NAT Gateway:CreateSnatEntry

Last Updated:Aug 28, 2026

Adds an SNAT entry to an SNAT table.

Operation description

Adds SNAT entries to Internet NAT gateways and VPC NAT gateways. In this topic, NAT gateway refers to both types.

Before you call this operation:

  • CreateSnatEntry is asynchronous. After you send a request, the system returns a request ID and runs the task in the background. Call DescribeSnatTableEntries to query the status.

    • If the SNAT entry is in the Pending state, it is being added. You can only query its status and cannot perform other operations.

    • If the SNAT entry is in the Available state, the entry is added.

  • Do not call CreateSnatEntry repeatedly within the specified period of time.

  • The vSwitch and ECS instance specified in an SNAT entry must be in the VPC where the NAT gateway is deployed.

  • Each vSwitch or ECS instance can be specified in only one SNAT entry.

  • You cannot create SNAT entries for a vSwitch that contains a high-availability virtual IP address (HAVIP).

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 region ID of the NAT gateway.

Call DescribeRegions to query available regions.

Valid values:

  • ap-northeast-2-pop

    :

    ap-northeast-2-pop

    .

Valid values:

  • ap-northeast-2-pop :

    ap-northeast-2-pop

cn-hangzhou

SnatTableId

string

Yes

The ID of the SNAT table.

stb-bp190wu8io1vgev****

SourceVSwitchId

string

No

The ID of the vSwitch.

  • For Internet NAT gateways, ECS instances in the specified vSwitch use this SNAT entry to access the Internet. If multiple EIPs form an SNAT address pool, connections are hashed across them and traffic may be unevenly distributed. To prevent service interruptions from individual EIP bandwidth limits, associate these EIPs with the same EIP bandwidth plan.

  • For VPC NAT gateways, ECS instances in the specified vSwitch use this SNAT entry to access external networks.

vsw-bp1nhx2s9ui5o****

SourceCIDR

string

No

The CIDR block of a VPC, vSwitch, ECS instance, or a custom CIDR block.

Valid CIDR block types:

  • VPC CIDR block: all ECS instances in the VPC access the Internet or external networks through SNAT.

  • vSwitch CIDR block (for example, 192.168.1.0/24): ECS instances in the vSwitch access the Internet or external networks through SNAT.

  • ECS instance IP address (for example, 192.168.1.1/32): the ECS instance accesses the Internet or external networks through SNAT.

  • Custom CIDR block: all ECS instances in the CIDR block access the Internet or external networks through SNAT.

For Internet NAT gateways, if SnatIp is set to one EIP, the ECS instance uses that EIP. If multiple EIPs are specified, the instance randomly selects one.

This parameter is mutually exclusive with SourceVSwitchId.

10.1.1.0/24

SnatIp

string

No

  • For Internet NAT gateways: the EIPs in the SNAT entry. Separate multiple EIPs with commas (,).

Note

If you specify multiple EIPs, connections are hashed across them and traffic may be unevenly distributed. Associate the EIPs with an Internet Shared Bandwidth instance to prevent service interruptions from bandwidth exhaustion.

  • For VPC NAT gateways: the NAT IP addresses in the SNAT entry. Separate multiple NAT IP addresses with commas (,).

47.98.XX.XX

SnatEntryName

string

No

The name of the SNAT entry.

The name must be 2 to 128 characters in length. It must start with a letter but cannot start with http:// or https://.

SnatEntry-1

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 across requests. The token can contain only ASCII characters.

Description 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.

02fb3da4-130e-11e9-8e44****

EipAffinity

integer

No

Specifies whether to enable EIP affinity. Valid values:

  • 0: no

  • 1: yes

Description When enabled and multiple EIPs are associated with the SNAT entry, each client uses a fixed EIP for Internet access. When disabled, each client uses a random EIP.

1

NetworkInterfaceId

string

No

The elastic network interface (ENI) ID.

Note

The IPv4 addresses of the ENI are used as the SNAT address.

eni-gw8g131ef2dnbu3k****

DryRun

boolean

No

Specifies whether to perform a dry run. Valid values:

  • true: performs a dry run without creating an SNAT entry. The system checks AccessKey validity, RAM user authorization, and required parameters. If the check fails, the corresponding error is returned. If all checks pass, the DryRunOperation error code is returned.

  • false (default): sends the request. If validation passes, a 2xx HTTP status code is returned and the SNAT entry is created.

false

Response elements

Element

Type

Description

Example

object

The ID of the SNAT entry.

SnatEntryId

string

The ID of the SNAT entry.

snat-kmd6nv8fy****

RequestId

string

The request ID.

2315DEB7-5E92-423A-91F7-4C1EC9AD****

Examples

Success response

JSON format

{
  "SnatEntryId": "snat-kmd6nv8fy****",
  "RequestId": "2315DEB7-5E92-423A-91F7-4C1EC9AD****"
}

Error codes

HTTP status code

Error code

Error message

Description

400 UnsupportedFeature.PrivateLinkEnabled The feature of PrivateLinkEnabled is not supported.
400 InvalidSourceCIDR.Malformed SourceCIDR is illegal.
400 NOT_ALLOW_USE_SOURCECIDR_OUTSIDEVPC The User not in sourcecidr_unlimited_outsidevpc white list. Cannot use SourceCidr outside VpcCidr.
400 NOT_ALLOW_USE_SOURCECIDR_AUTODEFINE The User not in sourcecidr_unlimited_insidevpc white list. Cannot use SourceCidr auto defined.
400 NOT_ALLOW_USE_SOURCECIDR_CONTAINSZERO The User not in sourcecidr_unlimited_outsidevpc_containszero white list. Cannot use SourceCidr outside VpcCidr.
400 Forbidden.IpHasBeenUsedInDnat The snat ip can't be used. Because it has been used in dnat
400 Forbidden.SourceVSwitchId.IncludeHaVip There is some HaVips under specified vSwitch The specified vSwitch is associated with HAVIPs.
400 InvalidSnatIp.Malformed The specified SnatIp is not a valid IP address.
400 SNAT_IP_POOL_COUNT_TOO_MANY The Snat pool ip too many.
400 Forbidden.SnatEntryCountLimited SNAT entry in the specified SNAT table reach its limit. The number of SNAT entries has reached the upper limit.
400 NOT_ALLOW_USE_SOURCECIDR The User not in nat_scope_unlimited white list. Cannot use SourceCidr param.
400 INVALID_PARAMETER The parameter invalid.
400 Forbidden.SourceVSwitchId.Duplicated The specified SourceCIDRis duplicated.
400 Forbidden.IpUsedInForwardTable The specified SnatIp already used in forward table
400 Forbindden The specified Instance already bind eip
400 EIP_NOT_SUPPORT_SNAT_POOL The Eip cannot support snat pool
400 EIP_NOT_IN_GATEWAY The Eip not in nat gateway
400 OperationUnsupported.CidrConflict The specified CIDR block conflicts with an existing SNAT entry. The specified CIDR block conflicts with those in existing SNAT entries.
400 InvalidNatGatewayId.NotFound The NatGateway instance not exist.
400 InvalidParameter.Name.Malformed The specified Name is not valid.
400 InvalidParameter.SnatIp Ip semgment must be subnet cidr.
400 QuotaExceeded.SnatIp Public ip number exceeds quota.
400 OperationUnsupported.EipInBinding Create snat entry with eip in associating status is unsupported. You cannot use an associated EIP when you create an SNAT entry.
400 OperationFailed.VSwitchNotInVpc The specified vswitch and natgateway are not in the same vpc.
400 QuotaExceeded.SnatEntry SNAT entry in the specified SNAT table reach it?s limit.
400 IncorrectStatus.NATGW NATGW status is invalid. The NAT gateway is in an invalid state.
400 IncorrectStatus.vSwitch The specified vSwitch status is invalid. The virtual switch status is abnormal.
400 MissingParam.SnatIp The input parameter SnatIp that is mandatory for processing this request is not supplied. You need to specify the SnatIp parameter when creating a Snat rule for public network NAT or private network NAT.
400 MissingParam.NetworkInterfaceId The input parameter NetworkInterfaceId that is mandatory for processing this request is not supplied. You need to specify NetworkInterfaceId parameters when creating a Snat rule for NAT with the private network link service enabled.
400 ParamExclusive.SnatIpAndNetworkInterfaceId SnatIp and NetworkInterfaceId is mutually exclusive when create a snat entry for nat. When you create an SNAT rule for a NAT Gateway instance, you cannot specify the SnatIp parameter and the NetworkInterfaceId parameter at the same time.
400 IllegalParam.NetworkInterfaceId The param of NetworkInterfaceId is illegal. Invalid NetworkInterfaceId value.
400 OperationUnsupported.EipNatBWPCheck The EIP is not associated with a NAT service plan. The EIP is not associated with a NAT service plan.
400 OperationUnsupported.EipNatGWCheck The operation failed because the EIP is not bound to this NAT Gateway. The operation failed because the EIP is not bound to this NAT Gateway.
400 OperationFailed.SnatIpPoolCbwpRules The operation failed because the SNAT rule IPs are added to multi bandwidth packages. The operation failed because the SNAT rule IP address pool was added to multiple bandwidth packages.
400 IncorrectStatus.SnatEntry The SNAT rule status is invalid. Please try again later. The SNAT rule is in the intermediate state, or the status is abnormal. Please try again later.
400 IncorrectStatus.NatIp NatIp status is invalid, please try again later. NatIp is in intermediate state, please try again later.
400 OperationUnsupported.EipNatIpCheck The operation failed because the EIP is not bound to this NAT gateway. The operation failed because the EIP is not bound to this NAT gateway.
400 OperationFailed.SnatIpPoolBwpRules The operation failed because the IP in Snat entryl was added to multiple NAT bandwidth packets. The operation failed because the IP in the SNAT rule IP address pool was added to multiple NAT bandwidth packets.
400 OperationFailed.SnatIpsCheck The operation fails because some IPs address in the SNAT entry are not added to common bandwidth packet. The operation fails because the IP address in the Snat rule IP address pool is not added to the shared bandwidth packet.
500 DefaultValidate.Error validte fail.
500 OperationFailed.CrateSnatEntryTimeOut Operation failed because create snatEntry timeout.
404 InvalidRegionId.NotFound The specified RegionId does not exist in our records.
404 InvalidSnatTableId.NotFound Specified SNAT table does not exist.
404 InvalidVSwitchId.NotFound The specified virtual switch does not exists.
404 InvalidSnatIp.NotFound Specified SnatIp does not found on the NAT Gateway
404 ResourceNotFound.NatGateway The NatGateway instance not exist. The NAT gateway does not exist.
404 ResourceNotFound.NatIp The NatIp instance not exist.
404 ResourceNotFound.vSwitch The specified resource of %s is not found. The specified vSwitch does not exist, please check your input is correct

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.