What is a GraphQL Circuit Breaker in a federated API?

A GraphQL circuit breaker in Cosmo Router monitors subgraph request outcomes. When failures exceed your configured thresholds, the router stops sending traffic to that subgraph so a slow or failing service does not cascade into a broader API outage.

How does Cosmo stop cascading failures across subgraphs?

Cosmo tracks error rate in a rolling time window. When the error threshold is exceeded and the minimum request count is met, the circuit opens. Requests to that subgraph are rejected immediately, keeping router resources available for the rest of the graph.

What do closed, open, and half-open mean?

Closed is normal operation with error tracking. Open means the router blocks traffic to the subgraph until a sleep window passes. Half-open means a small number of test requests probe recovery. Enough successes close the circuit; failures reopen it.

Can I use different circuit breaker settings per subgraph?

Yes. You can set global defaults and override thresholds, sleep windows, and half-open test rules per subgraph. You can also disable the circuit breaker per subgraph in development so you see every failure without circuit interference.

How do I disable the circuit breaker for a specific subgraph?

In the router traffic shaping configuration, add a per-subgraph override and turn the circuit breaker off for that subgraph only (for example `circuit_breaker.enabled: false` under that subgraph’s entry). Use this when you need every failure visible for one service or in a specific environment.

Where is the Cosmo Router circuit breaker configured?

You configure it in the router config file (config.yaml) under traffic shaping and circuit breaker, alongside retries and timeouts. You do not deploy anything extra to individual subgraphs.

How do retries and metrics work with the circuit breaker?

When a circuit is open, retries stop for that path, which helps prevent retry storms against a struggling service. Circuit breaker metrics provide visibility into circuit state and recovery behavior.

GraphQL Circuit Breaker | Cosmo

The problem

One failing subgraph can take down your whole GraphQL API

Each service in your federated graph can fail on its own. When one does, cascading failures spread across your GraphQL API.

Failures cascade across your entire API

When a subgraph becomes slow or unresponsive, requests can pile up, resources are exhausted, and the router can become unresponsive.

Timeouts waste resources on failing services

Without circuit breakers, requests continue waiting on a degraded dependency. Router resources stay tied up instead of being freed for healthy parts of the graph.

Recovery depends on manual intervention

Without automatic circuit protection, teams have to stop traffic to failing services by hand and decide when it is safe to restore it.

Our solution

Contain subgraph failures without losing the whole API

The router tracks each subgraph on every request. When failures exceed your thresholds, it opens the circuit, rejects requests immediately, and probes recovery after the sleep window.

What happens when the circuit breaker trips

A request to a subgraph fails, and the error rate rises inside the rolling window.
When the configured threshold is exceeded and the minimum request count is met, the circuit opens.
Requests to that subgraph are rejected immediately instead of waiting for timeouts.
Healthy subgraphs continue resolving normally while the failed service is isolated.
After the sleep window, the circuit moves to half-open and allows limited test requests.
If enough test requests succeed, the circuit closes. If a test request fails, it opens again.

The failure stays contained while recovery happens through configurable half-open testing.

Partial outages

Built for partial outages

In federated GraphQL, not every outage affects the whole graph. A database issue, network failure, or timeout in one subgraph can still consume router resources and slow unrelated requests.

Cosmo Router uses circuit breakers to isolate the affected subgraph once failure thresholds are exceeded. Requests to that subgraph are rejected immediately while healthy parts of the graph continue operating.

After the sleep window, the router tests recovery through the half-open state before restoring normal traffic.

Circuit logic

What counts as a failure

The circuit breaker tracks network-level and transport-level failures:

Connection refused errors
DNS errors
TLS failures
Broken connections
Read/write timeouts
Circuit breaker execution timeouts

These contribute to the error rate.

These do not

HTTP 4xx or 5xx responses when a response is received
Request cancellations
Client-side timeouts

If the subgraph returns an HTTP response, the circuit breaker does not treat that response as a transport failure.

How a GraphQL circuit breaker works

01

Failures hide in aggregate latency.

Detect

Set the rolling window and error threshold. The circuit opens when the threshold is exceeded and the minimum request count is met.

02

One slow subgraph can stall the graph.

Isolate

Requests to the affected subgraph are rejected immediately while the circuit is open, freeing router resources for the rest of the graph.

03

Blind retries amplify outages.

Test

After the sleep window, the router enters half-open state and allows a limited number of test requests.

04

Recovery should not be guesswork.

Restore

If enough test requests succeed, the circuit closes and normal traffic resumes. If a test request fails, the circuit opens again.

Router controls

Tune the circuit breaker per subgraph

Set limits per subgraph, ship changes from one config, and watch circuit state in your existing metrics stack.

Set rules per subgraph

Traffic shaping

Different services fail in different ways, so Cosmo lets you tune circuit breaker behavior independently.

Error rate

Open the circuit when failures exceed a threshold.

Time window

Controls how fast the circuit reacts.

Short window = faster response.

Long window = more stability.

Retry behavior

Retries stop when the circuit opens.

Recovery requires successful probes before traffic returns.

Metrics & monitoring

Observability

Monitor circuit breaker state, error rates, and recovery behavior through router metrics. Use those signals to alert on open circuits and confirm recovery.

Circuit breaker metrics documentation

One config. No code changes.

Cosmo Router

Add circuit breakers in a single config file.

No changes to your subgraphs.

Where the circuit breaker runs

System boundary

The circuit breaker runs inside the GraphQL router, where it tracks request outcomes and applies protection before failures spread across the graph.

When a circuit opens:

requests stop immediately
traffic is cut at the router
healthy subgraphs continue resolving normally

Failure is isolated to the subgraph. Not the whole API.

Example YAML configuration

Configuration

The Cosmo Router handles federated API resilience at the subgraph level: no service mesh required, no code changes in your subgraphs.

1

2

3

4

5

6

7

8

9

10

11

Configure circuit breakers in Cosmo Router

Built into Cosmo Router and configured through traffic shaping.

Book a demo Get started

Keep your API running when a subgraph fails