Reactor backpressure at an API boundary
Reactor backpressure controls demand within a cooperating stream; it does not automatically enforce an external API quota. Bound concurrent calls, enforce request-rate policy separately, and define where excess work waits or is rejected across every subscription and replica.
Inside this article 5 sections +
A Reactor pipeline can respect downstream demand and still overwhelm an external API. Demand describes how many elements a subscriber is ready to receive. A provider quota may instead describe requests per second across an account, while its infrastructure also has a limit on simultaneous work. Those are different contracts.
Consider a product that enriches imported company records through an external service. The import produces records quickly, enrichment takes variable time, and the result is written to a database. The design needs to connect all three stages without allowing the fastest one to accumulate unlimited work for the slowest.
Name the three limits in their own units
The first limit is stream demand: elements requested from upstream. The second is concurrency: requests currently in flight. The third is rate: requests started within a time interval. A fourth practical constraint is storage for waiting elements, measured in records and bytes. Using one number for all of these hides the actual failure behavior.
For example, allowing ten simultaneous calls does not establish ten requests per second. If each call completes quickly, those slots can turn over many times within a second. If the provider slows down, the same concurrency may produce far fewer starts while holding connections for longer. Rate and concurrency policies must therefore be evaluated independently.
- Demand
- How many upstream records may be requested by this stream?
- Concurrency
- How many provider requests may be active at once?
- Rate
- How many attempts may start per quota interval?
- Buffer
- How many records and bytes may wait, and where are they stored?
Bound inner work and account for subscriptions
A flatMap concurrency setting can limit the number of inner publishers subscribed at once within that operator instance. It is useful when each inner publisher represents one deferred external request. If the adapter starts work eagerly before subscription, the operator cannot retroactively constrain those already-started calls. Verify when the client actually initiates network activity.
Also inspect prefetch and buffering behavior. Restricting inner concurrency does not imply that no upstream elements are held in memory. Payload size matters: a few hundred identifiers and a few hundred full documents have very different memory costs. Measure retained bytes and keep large input content in durable storage where possible.
The scope is especially easy to miss in request-driven applications. If each incoming HTTP request constructs its own enrichment stream, a local limit of ten may apply independently to every caller. Multiple subscriptions and replicas multiply exposure. A shared provider account needs an admission mechanism whose scope matches that account, or a conservative allocation across instances.
Place rate admission before the external effect
Acquire permission to start a provider attempt immediately before the network operation. Count retries as attempts against the same policy. Do not issue the request and then delay delivery of its result; that slows the consumer while leaving provider load unchanged. The admission layer should expose waiting time and rejection so the pipeline can report meaningful outcomes.
Choose what happens when permission is unavailable. A small bounded in-memory wait may be suitable for an interactive lookup. A long-running import is often better represented by durable work that can resume. Dropping records may be acceptable for a replaceable telemetry stream, but silently dropping customer import rows is usually a product defect.
Reactive demand is effective only where the upstream producer cooperates. A third-party callback or hot event source may continue emitting regardless of downstream readiness. Its adapter needs an explicit overflow strategy and observability. Adding an unbounded buffer converts overload into memory growth and postpones the decision until the process fails.
Handle cancellation without assuming the world stopped
When a user cancels an import, cancel local subscriptions and stop admitting new provider requests. Then distinguish requests that never started from those already in flight. An HTTP cancellation may release local resources while the remote service still completes its work. Whether that matters depends on whether the call is a read or a business mutation.
For mutations, preserve operation identity and reconcile uncertain outcomes. For reads, decide whether late results can be discarded or retained for a resumable import. Apply deadlines across admission wait and execution rather than giving each stage a fresh unlimited budget. A record whose deadline expires while waiting should not quietly start a costly call afterward.
Test demand and external starts separately
Use a controlled provider with variable latency and an observable request-start log. Run one stream, multiple simultaneous streams, and the intended maximum replica configuration. Check active requests, starts per quota interval, buffer occupancy, completed records, and cancellation behavior. This reveals whether a local operator setting has been mistaken for a deployment-wide guarantee.
Slow the provider while keeping input arrivals unchanged. The expected result is bounded waiting, controlled rejection, or durable backlog according to the chosen policy. The reactive resource guide explains the execution tradeoff, and worker capacity tuning applies similar budgeting to durable jobs. Architecture design connects these controls at the actual resource boundary.