Keeping quotes reliable: the route-provider circuit breaker

herrenlos quotes several route providers at once and ranks them by what you'd actually receive (how swaps work here). That parallel model is what makes the routing good — but it also means the app depends on a handful of independent third-party APIs at the same time. Any one of them can slow down, rate-limit, or briefly fall over. This post is about the machinery that keeps one provider's bad day from becoming your bad quote: the circuit breaker and the provider-health checks behind it.

Why parallel quoting needs failure isolation

If you fan out to seven providers and treat them as one system, you inherit the worst of all seven. A single provider hanging on every request would make the whole Routes panel feel slow; a single provider erroring could, in a naive design, make it look like "swaps are down" when six others are perfectly healthy.

So each provider is isolated behind its own breaker. A provider is judged only on its own recent behavior, and a failing one is routed around, not allowed to drag the others down.

What the breaker actually does

A circuit breaker is a simple idea borrowed from electrical wiring: when something downstream keeps failing, stop hammering it and give it room to recover. Per provider, it moves through three states:

• Closed (normal). Requests flow through as usual.
• Open (tripped). After a provider fails repeatedly in a short window, its breaker opens: herrenlos stops sending it new quote requests for a cooldown period and just uses the other providers. This is the "route around it" state — it also means we're not making a struggling upstream worse by retrying into it.
• Half-open (testing recovery). Once the cooldown elapses, the next request is a trial. If it succeeds, the breaker closes and the provider is back in the rotation. If it fails again, the breaker re-opens with a longer cooldown — so a provider that's genuinely down is checked less and less often instead of on every single quote.

Two signals feed this, because "is it broken?" has more than one shape. One is a consecutive-failure count in a short window — good for catching a provider that's outright erroring or timing out. The other is a rolling success rate over the provider's recent calls: a provider that answers most of the time but returns errors or timeouts often enough (say, below ~70% success over a meaningful sample) gets proactively benched too, even if it never strings together enough back-to-back failures to trip the first check. Together they catch both "hard down" and "quietly unreliable."

Real failures vs. benign "no route"

A key detail that keeps the breaker honest: not every empty answer is a failure. When a provider cleanly says "I can't route this pair" — the amount is below its minimum, or it doesn't support that token/chain — that's a normal, correct response from a healthy API, not an outage. herrenlos treats those benign "no route" cases as a success for health purposes, so they never trip a breaker or bench a provider that's working fine. Only genuine upstream trouble — errors, timeouts, rate-limit storms — counts against a provider's health. (You'll still just see "no route from that provider for this trade," which is the truth.)

What you actually see when a provider is unhealthy

The whole point is that this stays calm and legible rather than alarming:

• Routes keep showing. If a provider is benched, herrenlos surfaces routes from everyone else and says so — a quiet line like "[provider] is temporarily unavailable — showing routes from other providers." It does not tell you swaps are down, because they aren't.
• Early-warning, not just on/off. When a provider is degrading but not yet benched, you may see a gentle "returning slower or fewer quotes than usual — routes still showing" note. Fewer or slower quotes from one provider, not a broken panel.
• Honest health at a glance. Affected providers can show a small pill with their recent success rate and average latency, so the status reflects real measured behavior rather than a vague "something's wrong."
• Auto-recovery. Because of the half-open probe, a provider that comes back is picked up automatically on the next successful trial — no manual reset, no page reload.

Honest about what this does and doesn't do

Breakers reduce the blast radius of a provider problem — they keep one degraded API from blanking your Routes or making the app feel broken, and they stop herrenlos from flogging an upstream that needs a moment. What they don't do is guarantee every provider is always available. If a provider is down, its routes genuinely aren't on offer for that window, and if no provider can serve a particular pair and size, herrenlos says that plainly rather than inventing a route. A missing provider is a missing route — never a fabricated one.

That's the trade we're comfortable making: fewer, honest quotes when something's degraded, and the full set back the moment it recovers.

See it in context

The swaps post walks through the parallel-quote model this protects, and the swap page is where it all plays out — most of the time you'll never notice the breaker at all, which is exactly the idea. The roadmap tracks reliability and provider work as it ships.