ApsaraMQ for RocketMQ throttles message operations when system capacity is insufficient or usage exceeds a specified threshold. Throttling protects underlying resources from overload by temporarily rejecting requests.
When throttling is triggered, the broker rejects the request and returns a system throttling error or a request timeout error. The specific error depends on your client protocol and SDK version.
Causes
Two scenarios trigger throttling:
High storage pressure -- A consumer group begins consuming from the maximum offset of the queue. This typically happens during new business rollouts where consumption must start before a specific point in time. The sudden spike in storage pressure on the queue triggers throttling.
Excessive message accumulation -- Consumers process messages slower than producers send them, causing messages to pile up in the queue. When the number of accumulated messages exceeds the threshold, the broker triggers throttling to reduce load on the downstream system.
Error codes and client behavior
TCP clients
| Field | Value |
|---|---|
| Error code | 215 |
| Error message keyword | messages flow control |
| SDK version | Behavior when throttled |
|---|---|
| SDK for Java earlier than 1.9.0.Final | Requests time out. No automatic retry. |
| SDK for Java 1.9.0.Final or later | The SDK retries automatically with exponential backoff. |
For details on retry behavior, see Message retry.
HTTP clients
| Field | Value |
|---|---|
| Error code | 429 |
| Error message keyword | TooManyRequests |
When HTTP requests exceed the throttling threshold, the broker applies a backpressure mechanism: excess requests are temporarily suspended on the broker for approximately 10 milliseconds before the response is returned to the client. This smooths out traffic spikes without immediately failing the request.
Prevent throttling
The root cause of throttling is that peak traffic exceeds the capacity of your instance specification. To avoid throttling:
Monitor instance usage -- Use the observability feature to monitor the instance usage.
Choose the right instance specification -- Purchase an instance specification that meets your business requirements.
Handle unexpected throttling
If throttling occurs unexpectedly:
Rely on built-in retry -- With SDK for Java 1.9.0.Final or later, the SDK retries throttled requests automatically using exponential backoff.
Implement a fallback -- If the built-in retry does not resolve the issue, temporarily route traffic to an alternative system until the throttling condition clears.