Product Constraints and Usage Quota

Last updated:2026-01-30 14:40:38

Product Constraints and Usage Quota

Last updated: 2026-01-30 14:40:38

To ensure stable performance of the cluster, TDMQ for MQTT imposes some usage limits based on different sales specification differences. For key feature differences between sales specifications, refer to Product Series. Below introduces the dimensional limitations you may encounter when using MQTT.
Sales Specification Restrictions
Restriction Item
Specific Restrictions
Behavior after Exceeding Limit
Recommendation
Cluster TPS limit
Strictly limit according to the specifications selected on the purchase page.
Note: QoS and cleanSession parameter settings impact TPS calculation. 1 TPS is not fully equivalent to 1 message production/sending. For details, see Billing Overview.
After the TPS limit is exceeded, message production/consumption requests will be rejected and result in errors. For details, see Quota and Flow Control Mechanisms.
You can view related rate limiting metrics on the console. For details, see Monitoring Instructions.
When purchasing, please estimate the traffic volume based on actual conditions. When rate limiting occurs, you can choose to upgrade cluster specifications to handle traffic spikes.
Number of cluster client connections
Strictly limit according to the specifications selected on the purchase page.
Client connection rejected, connection request (CONNECT) error.
When purchasing, estimate the number of clients based on the actual situation. When the online client reaches the limit, you can choose upgrade cluster specifications.
Number of cluster subscriptions
30 × maximum number of client connections. The number of cluster subscriptions includes shared subscriptions and auto-subscriptions.
New client subscription rejected, subscription request (SUBSCRIBE) error.
When multiple subscription scenarios conflict with quota limits, rate limiting will be based on priority: "non-Clean Session subscriptions > automated subscription rules > client manual subscriptions". For details, see subscription instructions.
﻿
Number of Topic Filters subscribed by each client (client id)
30. The number of cluster subscriptions includes shared subscriptions and auto-subscriptions.
New client subscription rejected, subscription request (SUBSCRIBE) error.
When multiple subscription scenarios conflict with quota limits, rate limiting will be based on priority: "non-Clean Session subscriptions > automated subscription rules > client manual subscriptions". For details, see subscription instructions.
﻿
Cluster new connection rate
1/100 of the maximum number of online client connections in the cluster. For example, if the connection count limit of the cluster is 10,000, the number of new client connections allowed per second is 100. The maximum number of new connections per second is 100.
Client connection rejected, connection request (CONNECT) error.
﻿
Data Plane Service Usage Limits
To ensure server stability and performance, with consideration for open-source protocol standards and specifications, TDMQ for MQTT has the following limits. If specific restricted items conflict with current usage scenarios, corresponding operations can be performed based on recommendations in the table.
For platinum edition clusters, some restriction items can be adjusted through Tencent Cloud standard ticket service and expert support.
Restriction Item Category
Restriction Details
Specific Restrictions
Behavior after Exceeding Limit
Recommendation
resource naming
client ID client alias
Unique in a single cluster. If different clients or devices use the same client ID, resource preemption may occur, leading to decommission.
Character requirements: only supports digits 0-9, letters a-z or A-Z, and three special characters: -_@
Length: 128 bytes
Client connection rejected, connection request (CONNECT) will be rejected.
If the actual need exceeds the current specification limit, you can contact us through a ticket.
﻿
Topic Name
The MQTT protocol defines the channel and path for message transmission.
Character requirements: any UTF-8 encoded character
Length: 256 bytes
After the quota is reached, the client's message request (PUBLISH) will be rejected.
﻿
﻿
Topic directory level
8. The Topic name supports up to 7 '/' symbols.
After the quota is reached, the client's message request (PUBLISH) or subscription request (SUBSCRIBE) will be rejected.
﻿
message attributes message body
message body size
4MiB, only compute Payload size
An error occurs when a message is sent if the message size exceeds the quota.
If the actual need exceeds the current specification limit, you can contact us through a ticket.
﻿
The length of the ContentType property
256 bytes, only involves MQTT 5.0
Client connection (CONNECT) rejected or message request (PUBLISH) error.
﻿
﻿
Length of User Property attribute
8 KB, only involves MQTT 5.0
Attributes that exceed the limit will be ignored
﻿
﻿
The length of the CorrelationData property
8 KB, only involves MQTT 5.0
Attributes that exceed the limit will be ignored
﻿
﻿
Message attributes other than the message body length
16 KB
Attributes that exceed the limit will be ignored
﻿
﻿
Topic Alias maximum allowed number
Maximum 10 per client
Client connections exceeding the limit will be disconnected.
﻿
Message Retention Policy
Message retention period for unconsumed messages (including retained messages)
3 days
Messages will be deleted if they exceed the retention period.
Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
﻿
Maximum number of retained messages per cluster
10000
Once this limit is reached, requests to send new retained messages (PUBLISH) to the server will be rejected.
﻿
message sending and receiving
Maximum unacknowledged message count (QoS >0) for single cluster service
For QoS 1 and 2 messages, the maximum unconfirmed message count per client is 8.
The server will disconnect the client connection if it receives messages exceeding the limit.
Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
﻿
Maximum unacknowledged message count (QoS >0) sent by the server in a single cluster
For QoS 1 and 2 messages, the maximum unconfirmed message count per client is 16.
Clients using the MQTT 5 protocol can adjust the limit through Receive Maximum, with a maximum of 128.
After reaching the quota, the server stops sending messages to the client.
﻿
﻿
HTTP API
A single HTTP connection occupies one connection specification. A single call counts TPS as QoS 1 messages. View API usage details.
After reaching the quota, calls will report errors.
﻿
﻿
Message retry policy
For QoS 1 and 2 messages, the default retry interval is 120 seconds with no limit.
-
﻿
﻿
Number of queued messages per cluster
No quantity limit, but subject to message retention period
-
﻿
﻿
Message send/consumption rate per cluster with retention
100 messages/second
An error will be reported when sending a request after reaching the quota. The server will be paused from sending messages to the client.
﻿
Client Connection
Client heartbeat check cycle
(Keep Alive Interval)
30-1200 seconds. According to the protocol, if the server does not receive any message within 1.5 times the set Keep Alive interval, it will determine the current connection as invalid.
If the time set by the client exceeds this limit (default is 1200s), it will be considered as 1200s; if the time set by the client is less than 30s, it will be considered as 30s.
-
﻿
Number of new connections per client ID
Once per second, 10 times per minute
Client connection rejected, connection request (CONNECT) error.
-
﻿
Check the online status of an online client via HTTP
A single HTTP connection occupies one connection specification. A single message call counts TPS as QoS 1 messages. View API usage details.
Exceeding the limit causes API call failure.
When purchasing, estimate the number of clients based on the actual situation. When the online client reaches the limit, you can choose upgrade cluster specifications.
﻿
WebSocket connection time
24 hours.
Exceeding the connection time causes automatic disconnection.
-
﻿
Offline client status retention time
﻿
Default retention period is 1 day.
You can use the MQTT 5 protocol client settings Session Expiry Interval to adjust the retention time, maximum 3 days.
Client status will be deleted if it exceeds the retention time.
Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
﻿
Offline client status limit
Offline and online clients share the cluster's client connection limit
When the number of online clients + offline clients exceeds the cluster's client connection limit, additional client connections will be rejected.
﻿
Certificate
Number of server certificates per cluster
3
-
Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
﻿
Number of CA certificates per cluster
32
Exceeded automatic sign-up or manual registration failed
﻿
﻿
Client certificate signup quota per second
15
Registration failed when exceeded
﻿
auto-subscription
auto-subscription rule count
10
Cannot create new auto-subscription rules
Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
﻿
Number of subscriptions in each auto-subscription rule
20
Cannot add new subscription rules within the rule; additions will not take effect.
﻿
Shared subscription
Shared subscription group count cap per cluster
20
Subscription request (SUBSCRIBE) error when quota is reached
Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
﻿
Maximum number of subscription expressions per shared subscription group
10, i.e. the number of $share/{ShareName}/{filter} filters
Subscription request (SUBSCRIBE) error when quota is reached
﻿
﻿
Total TPS upper limit of subscribe and unsubscribe requests per shared subscription Group
10
Both subscription (SUBSCRIBE) and unsubscribe (UNSUBSCRIBE) requests from clients will report errors when the quota is reached.
﻿
﻿
Number of clients in each shared subscription group
1024
Subscription request (SUBSCRIBE) error when quota is reached
﻿
Other Features
Number of properties for one client
10 pairs of Key: Value combinations. For details, see Properties
After the limit is exceeded, requests to add new properties will fail with an error. You need to call the API to delete the corresponding properties before adding them again.
﻿
﻿
Number of device identities in a single cluster
The maximum number of device identities that can be registered is 5 times the cluster's "Online Connections" specification. For example, a cluster with 2,000 TPS and 2,000 connections can register up to 10,000 device identities.
Exceeding the limit will cause the registered device identity API to report an error.
﻿
MQTT Protocol Usage Limits
TDMQ for MQTT currently supports all features of V3.1.1 and all features of the 5.0 protocol except the following:
1. Not supported AUTH request;
2. Not supported Will Delay Interval;
3. Not supported Server Redirection;
4. The Topic Alias feature is currently in gradual rollout. If needed, please contact us;
5. When QoS = 2, in extreme cases such as network jitter, message duplication may occur. Perform idempotent processing when necessary.

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Feedback

Restriction Item	Specific Restrictions	Behavior after Exceeding Limit	Recommendation
Cluster TPS limit	Strictly limit according to the specifications selected on the purchase page. Note: QoS and cleanSession parameter settings impact TPS calculation. 1 TPS is not fully equivalent to 1 message production/sending. For details, see Billing Overview.	After the TPS limit is exceeded, message production/consumption requests will be rejected and result in errors. For details, see Quota and Flow Control Mechanisms. You can view related rate limiting metrics on the console. For details, see Monitoring Instructions.	When purchasing, please estimate the traffic volume based on actual conditions. When rate limiting occurs, you can choose to upgrade cluster specifications to handle traffic spikes.
Number of cluster client connections	Strictly limit according to the specifications selected on the purchase page.	Client connection rejected, connection request (CONNECT) error.	When purchasing, estimate the number of clients based on the actual situation. When the online client reaches the limit, you can choose upgrade cluster specifications.
Number of cluster subscriptions	30 × maximum number of client connections. The number of cluster subscriptions includes shared subscriptions and auto-subscriptions.	New client subscription rejected, subscription request (SUBSCRIBE) error. When multiple subscription scenarios conflict with quota limits, rate limiting will be based on priority: "non-Clean Session subscriptions > automated subscription rules > client manual subscriptions". For details, see subscription instructions.
Number of Topic Filters subscribed by each client (client id)	30. The number of cluster subscriptions includes shared subscriptions and auto-subscriptions.	New client subscription rejected, subscription request (SUBSCRIBE) error. When multiple subscription scenarios conflict with quota limits, rate limiting will be based on priority: "non-Clean Session subscriptions > automated subscription rules > client manual subscriptions". For details, see subscription instructions.
Cluster new connection rate	1/100 of the maximum number of online client connections in the cluster. For example, if the connection count limit of the cluster is 10,000, the number of new client connections allowed per second is 100. The maximum number of new connections per second is 100.	Client connection rejected, connection request (CONNECT) error.

Restriction Item Category	Restriction Details	Specific Restrictions	Behavior after Exceeding Limit	Recommendation
resource naming	client ID client alias	Unique in a single cluster. If different clients or devices use the same client ID, resource preemption may occur, leading to decommission. Character requirements: only supports digits 0-9, letters a-z or A-Z, and three special characters: `-_@` Length: 128 bytes	Client connection rejected, connection request (CONNECT) will be rejected.	If the actual need exceeds the current specification limit, you can contact us through a ticket.
		Topic Name	The MQTT protocol defines the channel and path for message transmission. Character requirements: any UTF-8 encoded character Length: 256 bytes		After the quota is reached, the client's message request (PUBLISH) will be rejected.
		Topic directory level	8. The Topic name supports up to 7 '/' symbols.		After the quota is reached, the client's message request (PUBLISH) or subscription request (SUBSCRIBE) will be rejected.
message attributes message body	message body size	4MiB, only compute Payload size	An error occurs when a message is sent if the message size exceeds the quota.	If the actual need exceeds the current specification limit, you can contact us through a ticket.
		The length of the ContentType property	256 bytes, only involves MQTT 5.0		Client connection (CONNECT) rejected or message request (PUBLISH) error.
		Length of User Property attribute	8 KB, only involves MQTT 5.0		Attributes that exceed the limit will be ignored
		The length of the CorrelationData property	8 KB, only involves MQTT 5.0		Attributes that exceed the limit will be ignored
		Message attributes other than the message body length	16 KB		Attributes that exceed the limit will be ignored
		Topic Alias maximum allowed number	Maximum 10 per client		Client connections exceeding the limit will be disconnected.
Message Retention Policy	Message retention period for unconsumed messages (including retained messages)	3 days	Messages will be deleted if they exceed the retention period.	Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
Message Retention Policy		Maximum number of retained messages per cluster	10000		Once this limit is reached, requests to send new retained messages (PUBLISH) to the server will be rejected.
message sending and receiving	Maximum unacknowledged message count (QoS >0) for single cluster service	For QoS 1 and 2 messages, the maximum unconfirmed message count per client is 8.	The server will disconnect the client connection if it receives messages exceeding the limit.	Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
		Maximum unacknowledged message count (QoS >0) sent by the server in a single cluster	For QoS 1 and 2 messages, the maximum unconfirmed message count per client is 16. Clients using the MQTT 5 protocol can adjust the limit through Receive Maximum, with a maximum of 128.		After reaching the quota, the server stops sending messages to the client.
		HTTP API	A single HTTP connection occupies one connection specification. A single call counts TPS as QoS 1 messages. View API usage details.		After reaching the quota, calls will report errors.
		Message retry policy	For QoS 1 and 2 messages, the default retry interval is 120 seconds with no limit.		-
		Number of queued messages per cluster	No quantity limit, but subject to message retention period		-
		Message send/consumption rate per cluster with retention	100 messages/second		An error will be reported when sending a request after reaching the quota. The server will be paused from sending messages to the client.
Client Connection	Client heartbeat check cycle (Keep Alive Interval)	30-1200 seconds. According to the protocol, if the server does not receive any message within 1.5 times the set Keep Alive interval, it will determine the current connection as invalid.	If the time set by the client exceeds this limit (default is 1200s), it will be considered as 1200s; if the time set by the client is less than 30s, it will be considered as 30s.	-
		Number of new connections per client ID	Once per second, 10 times per minute	Client connection rejected, connection request (CONNECT) error.	-
		Check the online status of an online client via HTTP	A single HTTP connection occupies one connection specification. A single message call counts TPS as QoS 1 messages. View API usage details.	Exceeding the limit causes API call failure.	When purchasing, estimate the number of clients based on the actual situation. When the online client reaches the limit, you can choose upgrade cluster specifications.
		WebSocket connection time	24 hours.	Exceeding the connection time causes automatic disconnection.	-
		Offline client status retention time	Default retention period is 1 day. You can use the MQTT 5 protocol client settings Session Expiry Interval to adjust the retention time, maximum 3 days.	Client status will be deleted if it exceeds the retention time.	Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
		Offline client status limit	Offline and online clients share the cluster's client connection limit	When the number of online clients + offline clients exceeds the cluster's client connection limit, additional client connections will be rejected.
Certificate	Number of server certificates per cluster	3	-	Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
		Number of CA certificates per cluster	32		Exceeded automatic sign-up or manual registration failed
		Client certificate signup quota per second	15		Registration failed when exceeded
auto-subscription	auto-subscription rule count	10	Cannot create new auto-subscription rules	Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
auto-subscription		Number of subscriptions in each auto-subscription rule	20		Cannot add new subscription rules within the rule; additions will not take effect.
Shared subscription	Shared subscription group count cap per cluster	20	Subscription request (SUBSCRIBE) error when quota is reached	Platinum version clusters can be adjusted through Tencent Cloud standard ticket service and expert support.
		Maximum number of subscription expressions per shared subscription group	10, i.e. the number of `$share/{ShareName}/{filter}` filters		Subscription request (SUBSCRIBE) error when quota is reached
		Total TPS upper limit of subscribe and unsubscribe requests per shared subscription Group	10		Both subscription (SUBSCRIBE) and unsubscribe (UNSUBSCRIBE) requests from clients will report errors when the quota is reached.
		Number of clients in each shared subscription group	1024		Subscription request (SUBSCRIBE) error when quota is reached
Other Features	Number of properties for one client	10 pairs of Key: Value combinations. For details, see Properties	After the limit is exceeded, requests to add new properties will fail with an error. You need to call the API to delete the corresponding properties before adding them again.
Other Features		Number of device identities in a single cluster	The maximum number of device identities that can be registered is 5 times the cluster's "Online Connections" specification. For example, a cluster with 2,000 TPS and 2,000 connections can register up to 10,000 device identities.		Exceeding the limit will cause the registered device identity API to report an error.

tencent cloud

Sales Specification Restrictions

Data Plane Service Usage Limits

MQTT Protocol Usage Limits