​

What is waterfall routing?

Waterfall routing is the execution model Uniblock uses to reduce failover latency during provider selection. Instead of waiting for one provider to fully fail before the next provider is allowed to start, Uniblock can overlap provider attempts in a controlled sequence. The current backend implementation uses waterfall execution as the default backup strategy for routed requests. Providers are still tried in priority order, but the system can begin the next provider before the previous one fully finishes when a timeout window is reached. Use waterfall routing when you need:

• Faster recovery from slow or hanging upstream providers
• Lower tail latency during failover
• Priority-ordered backup behavior without strictly serial waiting
• Better resilience when some providers are degraded but not fully down

---

​

How it works

At a high level, Uniblock still builds a normal provider priority list first. Waterfall routing changes how that list is executed:

1. Build execution plan - Uniblock generates the provider list for the request, applies provider filters, removes disabled or rate-limited options, and preserves the final routing order
2. Start provider 1 - The top provider begins processing
3. Wait briefly for a result - If the provider fulfills the request quickly, execution stops and the response is returned
4. Open the next step in the waterfall - If the provider is still pending after the waterfall timeout, Uniblock starts the next provider in the priority list
5. Return the first fulfilled result - As soon as one provider fulfills the request, that response wins
6. Drain remaining work - Any in-flight handlers are allowed to finish in the background so request history is complete

In the current implementation, the waterfall executor uses:

• A 3 second waterfall timeout
• Up to 3 concurrent active provider handlers
• A first fulfilled result wins completion rule

---

​

What changes compared to standard backup failover?

Traditional backup failover is fully sequential:

1. Try provider A
2. Wait for provider A to succeed or fail
3. Then try provider B
4. Then try provider C

Waterfall routing is still ordered, but it does not force the system to wait for every slow provider to finish before moving on.

​

Example timeline

Assume your routed priority list is:

1. Alchemy
2. QuickNode
3. Ankr

With waterfall routing:

1. 0s - Alchemy starts
2. 3s - If Alchemy is still hanging, QuickNode starts
3. 6s - If neither has fulfilled the request, Ankr starts
4. 6.2s - If QuickNode fulfills successfully, Uniblock returns QuickNode’s response immediately

This means a slow provider can still win if it finishes first, but it no longer blocks the rest of the backup chain from starting.

---

​

When Uniblock skips a provider before the waterfall

Not every provider in the priority list results in an outbound request. Before a handler is started, Uniblock checks:

• Whether the provider has a handler for that endpoint
• Whether request constraints pass
• Whether the chain is supported
• Whether the provider is allowed by supportedProviders
• Whether the provider was filtered out by rate-limit state
• Whether the provider key can be loaded

If any of those checks fail, the provider is skipped and the waterfall advances to the next eligible option without waiting.

---

​

Fulfilled vs unfulfilled

Waterfall execution stops only when a provider fulfills the request. Requests are treated as unfulfilled when a provider:

• Throws an unhandled handler error
• Returns a provider error
• Times out from the request’s point of view
• Fails validation or transform logic
• Cannot satisfy the endpoint constraints

If no provider fulfills the request, Uniblock waits for any remaining in-flight handlers to finish and then returns the normal routed error response.

---

​

Relationship to auto-routing and backup providers

Waterfall routing does not replace auto-routing or backup providers. It sits inside that system:

• Auto-routing decides the provider priority order
• Backup providers define what the next eligible options are
• Waterfall routing controls how quickly Uniblock advances through that ordered list

That means waterfall routing improves failover latency without changing the fact that provider order still matters.

---

​

Rate limits and waterfall routing

Waterfall routing helps with provider-level failures and slowdowns, but it does not bypass Uniblock plan limits.

• If an upstream provider is unavailable or rate-limited, the waterfall can move to the next eligible provider
• If Uniblock itself returns a 429 because your project hit its plan-level limit, the waterfall does not override that limit

This is the same distinction described in the backup provider flow.

---

​

Observability notes

Waterfall execution affects how provider attempts appear in analytics and logs:

• The first provider in the priority list is still the first provider started
• Later providers may begin before earlier providers have fully completed
• History entries can be recorded in resolution order, not strict initiation order

That means waterfall attempts may look slightly different from a purely sequential fallback chain when you inspect request history.

---

​

Why this design is useful

Waterfall routing is a practical middle ground between two extremes:

• Strict serial failover is simple but slow when providers hang
• Fan-out to every provider at once is fast but expensive and wasteful

Waterfall routing keeps the cost and control benefits of an ordered backup list while reducing the latency penalty of waiting on degraded providers.

---

​

Related guides

---