> 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-listener/createlistener.md).
# CreateListener
## 1. API Description
This API (CreateListener) is used to create a listener for a load balancer.
{% hint style="info" %}
**Notes**
* `algoOpts` (stateless forwarding) and `persistent` (session persistence) are mutually exclusive because stateless forwarding hashes packets individually and does not maintain a connection-tracking table, so it cannot guarantee that the same client always hits the same backend.
{% endhint %}
## 2. Input Parameters
The following request parameter list only provides API request parameters.
| Parameter Name | Required | Type | Description |
| -------------- | -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| loadBalancerId | Yes | String | Load balancer instance ID.
It can be obtained by calling DescribeLoadBalancers.
|
| listenerName | Yes | String | Name of the listener to be created.
Only letters, numbers, hyphens (-), and periods (.) are supported, and the name must start and end with a letter or number.
|
| protocol | Yes | [ListenerProtocol](/api-reference/zlb/datastructure.md#listenerprotocol) | Listening protocols. |
| scheduler | Yes | [ListenerScheduler](/api-reference/zlb/datastructure.md#listenerscheduler) | Scheduling algorithm of the listener. |
| port | Yes | String | Listening port.
Multiple ports are separated by commas (,).
A port range is connected with -, for example: 10000-10005.
Valid port values range from 0 to 65535, where 0 indicates all ports.
Note that the ports must not overlap with other ports of this listener.
Both a port range and all ports are counted as 1 port in quota calculation.
Consecutive individual ports are automatically merged into a port range before being saved and returned. For example, 1,2,3,4,5 is saved as 1-5.
|
| healthCheck | No | [HealthCheck](/api-reference/zlb/datastructure.md#healthcheck) | Health check parameters.
If this parameter is not passed, or healthCheck.enabled is set to false, health check is disabled.
|
| kind | No | [LoadBalancerKind](/api-reference/zlb/datastructure.md#loadbalancerkind) | Forwarding mode.
If this load balancer already has listeners, the default value follows their forwarding mode; otherwise, the default value is set based on the region of the load balancer instance (the default value may be DNAT or FNAT).
All listeners under the same load balancer must use the same forwarding mode. In DR mode, the listener does not support being set to all ports (0).
When the ipStackType of the load balancer instance is IPv6, only DR is supported, and DR is used by default if it is not specified.
|
| persistent | No | Integer | Session persistence duration, in seconds.
Mutually exclusive with algoOpts (advanced scheduling-algorithm option): a non-zero value cannot be passed when this listener has algoOpts set.
Value range: \[0, +)
|
| idleTimeout | No | Integer | Idle timeout period. Unit: seconds.
Value range: \[60, +)
Default value: 300
|
| algoOpts | No | [ListenerAlgoOpts](/api-reference/zlb/datastructure.md#listeneralgoopts) | Advanced scheduling-algorithm option.
Can only be set when the forwarding mode (kind) is DR and the scheduling algorithm (scheduler) is mh; any other combination will cause the request to be rejected.
Passing None at creation time is equivalent to not setting this field.
Once enabled, it is mutually exclusive with session persistence (persistent) — both cannot be set to non-zero values at the same time.
|
## 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.
|
| listenerId | String | The created listener ID. |
## 4. Code Example
{% tabs %}
{% tab title="Example" %}
1. **Create a TCP load balance listener to listen to ports `8080-9000` and `8000` without enabling health check.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateListener
Request：
{
"loadBalancerId" : "",
"listenerName" : "sample",
"protocol" : "TCP",
"scheduler" : "mh",
"port" : "8080-9000,8000",
"persistent": 60,
"idleTimeout": 60
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"listenerId": ""
}
}
```
2. **Create a TCP load balance listener and enable health check at the same time.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateListener
Request：
{
"loadBalancerId" : "",
"listenerName" : "sample",
"protocol" : "TCP",
"scheduler" : "mh",
"healthChekc": {
"enabled": true,
"checkType": "HTTP_GET",
"checkPort": null,
"checkDelayLoop": 3,
"checkConnTimeout": 2,
"checkRetry": 2,
"checkDelayTry": 2,
"checkHttpGetUrl": "/health",
"checkHttpStatusCode": 200
},
"port" : "8080",
"persistent": 60,
"idleTimeout": 60
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"listenerId": ""
}
}
```
{% 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 |
| ---------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | INVALID\_ALGO\_OPTS\_NOT\_SUPPORTED | The advanced scheduling-algorithm option (`algoOpts`) is only supported when the forwarding mode (`kind`) is `DR` and the scheduling algorithm (`scheduler`) is `mh`. |
| 400 | INVALID\_ALGO\_OPTS\_PERSISTENT\_CONFLICT | The advanced scheduling algorithm option (stateless forwarding) and session persistence cannot be enabled simultaneously. |
| 409 | INVALID\_BACKEND\_INSTANCE\_LISTENER\_EXIST | Backend server already exists. |
| 409 | INVALID\_BACKEND\_INSTANCE\_MULTIPLE | Duplicated backend servers. |
| 400 | INVALID\_BACKEND\_IP\_ADDRESS | No instance found for the specified private IP of the backend server. |
| 409 | INVALID\_BACKEND\_IP\_ZBG\_REQUIRED | A border gateway is required for the VPC to which the backend server IP belongs. |
| 400 | INVALID\_BACKEND\_SERVER\_IP\_INVALID | Invalid backend server IP. The backend server IP must be a private IP. |
| 409 | INVALID\_BACKEND\_SERVER\_IP\_REPEAT | Duplicated backend server IPs. |
| 400 | INVALID\_BACKEND\_SERVER\_PORT | In DR mode, full port, or listening on multiple ports, the backend server port cannot be specified. |
| 400 | INVALID\_INSTANCE\_IP\_ADDRESS | The instance's private IP is invalid. |
| 404 | INVALID\_INSTANCE\_NOT\_FOUND | Backend server does not exist. |
| 404 | INVALID\_LB\_LISTENER\_NOT\_FOUND | The listener does not exist. |
| 404 | INVALID\_LB\_NOT\_FOUND | Load balancer does not exist. |
| 400 | INVALID\_LB\_STATUS | Load balancer state is not supported. |
| 409 | INVALID\_LISTENER\_KIND\_CONFLICT | The listener's forwarding mode is inconsistent with an existing listener on this load balancer. |
| 400 | INVALID\_LISTENER\_KIND\_DR\_ALL\_PORT\_NOT\_SUPPORT | A listener in DR mode does not support all-port (0). |
| 400 | INVALID\_LISTENER\_KIND\_NOT\_SUPPORT | The specified listener type is not supported in this region. |
| 409 | INVALID\_LISTENER\_PORT\_CONFLICT | The port conflicts with another listener. |
| 409 | INVALID\_LISTENER\_PORT\_CONFLICT\_SELF | The configured port is invalid due to a conflict. |
| 400 | INVALID\_LISTENER\_QUOTA\_EXCEED | The number of listeners on the load balancer exceeds limit. |
| 400 | INVALID\_PORT\_FORMAT\_ERROR | Invalid port format. |
| 400 | INVALID\_PORT\_RANGE | Invalid port range. The port range should be between 1 and 65535. |
| 400 | INVALID\_RS\_QUOTA\_EXCEED\_PER\_LISTENER | The number of backend servers under the listener exceeds the quota limit. |
| 400 | INVALID\_HEALTH\_CHECK\_PORT\_REQUIRED | When using TCP or HTTP health checks with an all-port listener, a health check port must be specified. |