Fix Pulsar Too Many Requests Rate Limit Errors (2026)

The Pulsar broker is rejecting client requests because it’s exceeding its configured rate limits, preventing clients from publishing or consuming messages.

The most common culprit is simply hitting the default rate limits. Pulsar brokers have built-in mechanisms to prevent abuse and ensure stability, and if your application’s traffic spikes beyond these defaults, you’ll see TooManyRequests errors.

Cause 1: Exceeded Topic Level Rate Limits

Diagnosis: Check the broker logs for messages like Topic rate limit exceeded for topic .... You can also inspect the topic’s configuration using the Pulsar admin CLI:
```
./pulsar-admin topics get-rate-limit my_topic
```
Look for publishRate and subscribeRate.
Fix: Increase the topic-level publish or subscribe rate limits. For example, to set a publish rate of 1000 messages per second and a bandwidth of 10MB/s:
```
./pulsar-admin topics set-publish-rate my_topic --rate 1000 --bandwidth 10M
```
To set a subscribe rate of 500 messages per second and 10MB/s:
```
./pulsar-admin topics set-subscribe-rate my_topic --rate 500 --bandwidth 10M
```
This bypasses the limit for this specific topic, allowing more traffic.

Cause 2: Exceeded Global Rate Limits

Diagnosis: If topic-level limits aren’t set or are very high, the global broker rate limits might be the issue. These are configured in the broker’s broker.conf file. Look for maxPublishRatePerBroker and maxSubscribeRatePerBroker. The default is often 10000 messages/sec and 100MB/s for publish, and 10000 messages/sec and 100MB/s for subscribe.
Fix: Increase the global rate limits in broker.conf on all brokers. For example, to increase the publish rate to 20000 messages/sec and 200MB/s:
```
maxPublishRatePerBroker=20000
maxPublishBandwidthPerBroker=200M
```
Then restart the Pulsar broker processes. This raises the ceiling for all topics handled by that broker.

Cause 3: Client-Side Rate Limiting Misconfiguration

Diagnosis: Sometimes, clients themselves have internal rate limiting enabled, or they are configured to connect with parameters that trigger broker-side limits prematurely. Check your client application’s configuration for any producer or consumer settings related to rate or batching.
Fix: Adjust client-side producer/consumer configurations. For example, in the Java client, you might need to increase maxPendingMessages or maxConcurrentInflightRequests. If using batching, ensure batchingMaxPublishDelayMicros is set appropriately to allow messages to accumulate before sending, potentially smoothing out bursts.
```
Producer<byte[]> producer = pulsarClient.newProducer()
    .topic("my_topic")
    .enableBatching(true)
    .batchingMaxPublishDelay(100, TimeUnit.MILLISECONDS) // Example: increase delay
    .create();
```
This allows the client to buffer more messages before sending them in batches, reducing the frequency of individual send requests.

Cause 4: Insufficient Broker Resources (CPU/Memory)

Diagnosis: High request rates can strain broker resources. Monitor your broker’s CPU and memory utilization. If they are consistently high (e.g., >80%), the broker might be struggling to process requests fast enough, leading to perceived rate limiting. Use tools like top, htop, or your cloud provider’s monitoring.
Fix: Scale up your broker instances (more CPU/RAM) or add more broker nodes to distribute the load. This provides the underlying hardware capacity for the broker to handle the traffic.

Cause 5: Network Latency or Bandwidth Issues

Diagnosis: High network latency or insufficient bandwidth between clients and brokers can cause requests to take longer, which can indirectly trigger rate limits if the client is configured with aggressive connection timeouts or if the broker’s internal processing queue backs up. Use ping and iperf3 to test network performance.
Fix: Improve network connectivity. This might involve optimizing network routes, increasing network interface speeds, or moving clients and brokers closer in terms of network topology.

Cause 6: Too Many Active Consumers/Producers on a Single Topic Partition

Diagnosis: While Pulsar is designed for high concurrency, an extremely large number of active consumers or producers on a single topic partition can still overwhelm the broker’s ability to manage connections and message delivery for that partition. Check the number of active consumers/producers for your topic using the admin API:
```
./pulsar-admin topics list-consumers my_topic
./pulsar-admin topics list-producers my_topic
```
Fix: If you have an excessive number of clients for a single partition, consider partitioning your topic. Creating a topic with multiple partitions (e.g., my_topic-partition-0, my_topic-partition-1) allows you to distribute the load across multiple partitions, each managed by a broker (or replica set).
```
./pulsar-admin topics create my_topic -p 4 # Creates 4 partitions
```
Clients can then connect to different partitions, distributing the overall load.

The next error you’re likely to encounter if you’ve fixed rate limiting but still have underlying issues is related to segment ownership or leadership election, indicating a different kind of cluster instability.