> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/zlb/load-balancer-instance/createloadbalancer.md).
# CreateLoadBalancer
## 1. API Description
This API (CreateLoadBalancer) is used to create a load balancer instance.
{% hint style="info" %}
**Notes**
* You can call [DescribeLoadBalancerRegions](/api-reference/zlb/location/describeloadbalancerregions.md) to check the regions that support purchasing load balancers.
* This API is asynchronous. After the request returns successfully, you can call [DescribeLoadBalancers](/api-reference/zlb/load-balancer-instance/describeloadbalancers.md) to query the state of the load balancer instance. A state of `RUNNING` indicates that the instance was created successfully.
* Currently, load balancer instances can only be created for ZEC servers.
* Only postpaid load balancer instances can be created.
* When creating a load balancer instance, make sure that the VPC has a subnet meeting the `ipStackType` requirement and that at least 2 addresses in the subnet are available for allocation.
* When an existing EIP is specified through `eipIds`, the EIP is associated only after the load balancer instance is created (its state becomes `RUNNING`). You can call [DescribeEips](/api-reference/zec/elastic-ip/describeeips.md) to query the association result.
{% endhint %}
## 2. Input Parameters
The following request parameter list only provides API request parameters.
| Parameter Name | Required | Type | Description |
| --------------------------- | -------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| regionId | Yes | String | Region ID.
It can be obtained by calling DescribeRegions.
|
| loadBalancerName | Yes | String | Load balance instance name.
Containing 1 to 64 characters.
Available range: \[1.0, +).
Value range: \[1.0, +)
|
| vpcId | No | String | ID of the VPC to which the backend servers of the load balancer belong.
At least one of vpcId and subnetId must be specified.
If only subnetId is specified, the VPC to which the subnet belongs is used.
It can be obtained by calling DescribeVpcs.
|
| subnetId | No | String | Subnet ID.
It can be obtained by calling DescribeSubnets.
At least one of vpcId and subnetId must be specified.
The subnet must be in the same region as regionId; if vpcId is also specified, the subnet must belong to that VPC.
When ipStackType is IPv4, the subnet must support IPv4 and this parameter is optional (the system selects one within the VPC). When ipStackType is IPv6, the subnet must contain a public IPv6 block (a private IPv6 block does not qualify) and this parameter is required: both the public IPv6 VIP and the health check block are allocated from this subnet, and MISSING\_PARAMETER is returned if it is not specified.
|
| healthCheckPrivateIps | No | Array of String | Health probe source private IP addresses; the quantity must be 2.
When subnetId is specified and this field is left empty, 2 available private IPv4 addresses are randomly allocated from that subnet as the health probe source IPs. Each load balancer instance occupies 2 addresses; if the subnet does not have enough available private IPv4 addresses remaining, INVALID\_SUBNET\_IPV4\_INSUFFICIENT is returned. The allocation result can be queried by calling DescribeLoadBalancers.
When subnetId is not specified, this parameter is invalid.
It can be specified only when ipStackType is IPv4. When ipStackType is IPv6, the health probe block is automatically allocated by the system from the public IPv6 block of the subnet, and specifying this parameter returns INVALID\_PARAMETER\_CONFLICT.
|
| ipStackType | No | [LoadBalancerIpStackType](/api-reference/zlb/datastructure.md#loadbalanceripstacktype) | IP stack type.
A load balancer instance supports only a single stack, that is, IPv4 or IPv6. Dual stack is not supported.
When IPv6 is specified, the public network parameters (internetChargeType, networkLineType, bandwidthMbps, trafficPackageSize, bandwidthClusterId) cannot be configured, and eipIds cannot be specified either, because all EIPs are IPv4. The public addresses of an IPv6 load balancer are assigned separately through AssignLoadBalancerIpv6.
Default value: IPv4
|
| eipIds | No | Array of String | List of IDs of existing elastic IPs to be associated with the new load balancer instance.
Both single-IP EIPs (mask /32) and block-type EIPs are supported. You can call DescribeEips to query them.
All EIPs must be in the same region as regionId and in the unassociated state.
When this parameter is specified, internetChargeType, networkLineType, bandwidthMbps, trafficPackageSize, and bandwidthClusterId do not take effect, no new EIP is created for the instance, and number can only be 1.
It can be specified only when ipStackType is IPv4.
|
| internetChargeType | No | [InternetChargeType](/api-reference/zlb/datastructure.md#internetchargetype) | IP network billing model.
This parameter does not take effect when eipIds is specified.
|
| ipNetworkType \[Deprecated] | No | [EipNetworkType](/api-reference/zlb/datastructure.md#eipnetworktype) | IP network type.
Deprecated. Use networkLineType instead.
|
| networkLineType | No | [NetworkLineType](/api-reference/zlb/datastructure.md#networklinetype) | IP network type. |
| bandwidthMbps | No | Integer | Maximum outbound bandwidth of the elastic IP. Unit: Mbps. The maximum limit is usually 10000 Mbps. If you have additional requirements, please contact Support. This parameter is required when internetChargeType is ByBandwidth.
Value range: \[1, +)
|
| trafficPackageSize | No | Float | Traffic package size.
When this parameter is specified, the IP network billing method (internetChargeType) must be ByTrafficPackage; otherwise this parameter does not take effect.
It can only be set when the billing period is monthly; hourly billing is not supported.
Value range: \[0.0, 999999.0]
|
| bandwidthClusterId | No | String | Bandwidth cluster ID.
When this parameter is specified, the IP network billing method (internetChargeType) must be BandwidthCluster; otherwise this parameter does not take effect.
|
| resourceGroupId | No | String | Resource Group ID
If not specified, the load balance instance will belong to the default resource group.
|
| number | No | Integer | The number of created load balancers.
Default value: 1
|
| marketingOptions | No | [MarketingInfo](/api-reference/zlb/datastructure.md#marketinginfo) | Information on marketing campaigns. |
| tags | No | [TagAssociation](/api-reference/zlb/datastructure.md#tagassociation) | Bound tags when creating the load balancer.
Tag keys must be unique.
|
| securityGroupId | No | String | ID of the security group associated with the load balancer instance.
It can be obtained by calling DescribeSecurityGroups.
|
## 3. Output Parameters
| Parameter Name | Type | Description |
| --------------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| requestId | String | The unique request ID, which is returned for each request.
RequestId is required for locating a problem.
|
| orderNumber | String | Order number. |
| loadBalancerIds | Array of String | A collection of unique IDs of the load balancer instances. |
## 4. Code Example
{% tabs %}
{% tab title="Example" %}
**1. Create a public load balancer instance. The IP billing method is fixed bandwidth.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request:
{
"regionId" : "asia-east-1",
"vpcId" : "",
"securityGroupId" : "",
"loadBalancerName" : "sample",
"internetChargeType" : "ByBandwidth",
"networkLineType" : "PremiumBGP",
"bandwidthMbps" : 2,
"trafficPackageSize" : null,
"bandwidthClusterId" : "",
"number" : 1
}
Response:
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
**2. Specify only `subnetId` without `vpcId`: the load balancer instance belongs to the VPC of the subnet, and 2 private IPv4 addresses are randomly allocated from the subnet as the health check source IPs.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request:
{
"regionId" : "asia-east-1",
"subnetId" : "",
"loadBalancerName" : "sample",
"internetChargeType" : "ByBandwidth",
"networkLineType" : "PremiumBGP",
"bandwidthMbps" : 2,
"number" : 1
}
Response:
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
**3. Create a load balancer instance with an existing elastic IP (EIP) instead of creating a new EIP.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request:
{
"regionId" : "asia-east-1",
"vpcId" : "",
"loadBalancerName" : "sample",
"eipIds" : ["", ""],
"number" : 1
}
Response:
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
**4. Create a load balancer instance with a POC voucher. If no POC voucher exists in the system, the creation will fail.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request:
{
"regionId" : "asia-east-1",
"vpcId" : "",
"securityGroupId" : "",
"loadBalancerName" : "sample",
"internetChargeType" : "ByBandwidth",
"networkLineType" : "PremiumBGP",
"bandwidthMbps" : 2,
"number" : 1,
"marketingOptions" : {
"usePocVoucher" : true
}
}
Response:
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
{% endtab %}
{% endtabs %}
## 5. Developer Resources
Zenlayer Cloud API 2.0 integrates [SDKs](/api-reference/api-introduction/toolkit/api-sdk.md)，to make it easier for you to call APIs. More programming languages will be supported.
## 6. Error Codes
The following only lists the error codes related to the API business logic. For other error codes, see [Common Error Codes](/api-reference/api-introduction/instruction/commonerrorcode.md).
| HTTP Status Code | Error Code | Description |
| ---------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 404 | INVALID\_EIP\_NOT\_FOUND | Elastic IP does not exist. |
| 400 | INVALID\_IP\_BROADCAST\_ADDRESS | Invalid IP address: broadcast addresses are not allowed. |
| 400 | INVALID\_IP\_FIRST\_ADDRESS | Invalid IP address: gateway addresses are not allowed. |
| 400 | INVALID\_IP\_NETWORK\_ADDRESS | Invalid IP address: network addresses are not allowed. |
| 400 | INVALID\_IP\_OUT\_OF\_RANGE | Invalid IP address: not within the CIDR range. |
| 400 | INVALID\_REGION\_MISMATCH | The EIP is not in the same region as the target resource. |
| 404 | INVALID\_REGION\_NOT\_FOUND | Specified region does not exist. |
| 404 | INVALID\_SECURITY\_GROUP\_NOT\_FOUND | Security group does not exist. |
| 409 | INVALID\_SUBNET\_IPV4\_INSUFFICIENT | There are not enough available IPv4 addresses in the subnet. |
| 409 | INVALID\_SUBNET\_IPV6\_INSUFFICIENT | The number of the available IPv6 addresses in the subnet is insufficient. |
| 400 | INVALID\_SUBNET\_NOT\_BELONG\_TO\_VPC | Specified subnet is not within the global VPC. |
| 404 | INVALID\_SUBNET\_NOT\_FOUND | Subnet does not exist. |
| 409 | INVALID\_SUBNET\_PRIVATE\_IPV4\_IN\_USED | Preset private IP is already be used. |
| 404 | INVALID\_VPC\_NOT\_FOUND | Global VPC does not exist. |
| 400 | OPERATION\_DENIED\_EIP\_ASSIGNED\_LIMIT\_EXCEEDED | Elastic IP binding exceeds the allowed limit. |
| 400 | OPERATION\_DENIED\_EIP\_INSUFFICIENT | Insufficient elastic IP addresses. Operation failed. |
| 400 | OPERATION\_DENIED\_EIP\_IS\_DEFAULT | Default public IP cannot be unbound. |
| 400 | OPERATION\_DENIED\_EIP\_IS\_NOT\_UN\_ASSIGN | The EIP is already occupied (not in the unbound state) and cannot be bound. |
| 400 | OPERATION\_DENIED\_EIP\_QUOTA\_LIMIT\_EXCEEDED | The number of elastic IP addresses exceeds limit. |
| 500 | OPERATION\_DENIED\_EIP\_STATUS\_NOT\_SUPPORT | The current EIP status does not support this operation. |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT | Subnet stack type is not supported. |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT\_IPV4 | IPv4 subnet stack type is not supported. |
| 400 | OPERATION\_DENIED\_SUBNET\_NOT\_SUPPORT\_PUBLIC\_IPV6 | The subnet does not have a public IPv6 block. |
| 409 | OPERATION\_DENIED\_NO\_AVAILABLE\_SUBNET | No valid subnet exists under the global VPC. Operation failed. |
| 400 | INVALID\_PARAMETER\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | PathBasedBandwidthIP does not support a custom traffic package size. Pass 0 or omit this parameter. |
| 400 | OPERATION\_DENIED\_FIXED\_BANDWIDTH\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | PathBasedBandwidthIP does not support fixed bandwidth billing. |
| 400 | OPERATION\_DENIED\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_HOUR\_PERIOD | The current product cycle is based on hourly billing and does not support setting a minimum data package size. |