Route Behavior

Chaos Injection

Real APIs fail sometimes, and your app's error handling only gets tested if it actually sees an error. Chaos injection makes a route fail at random, at a rate you choose, so you can watch your retry logic, error states, and loading fallbacks actually run.

How it works

Set an error rate between 0% and 100% in the route's Advanced section. On each request, MockBase rolls the dice independently: at a 20% rate, roughly 1 in 5 calls returns a failure instead of the route's normal response. It's a per-request roll, not a fixed pattern — you won't get exactly every 5th request failing.

The rate decides whether a request fails. What the failure looks like is up to the scenarios below.

Failure scenarios

With no scenarios configured, a failed request returns the single status code you picked (500 by default) with a fixed body identifying it as an injected failure. That's the simplest case, and it stays the default.

Add scenarios and a failure becomes a weighted draw instead — which matters because real outages aren't one repeated status code. Each scenario has:

  • a label, so a failure is identifiable rather than anonymous (it also comes back on the X-MockBase-Chaos-Scenario response header)
  • a weight, its share of the failures relative to the others — a scenario with weight 3 alongside one with weight 1 accounts for 75% of them
  • a status code
  • a delay, held before responding — this is how you model a slow failure or a near-timeout, which a status code alone can't do
  • an optional custom body, served exactly as written — or Reset connection instead, covered below, which replaces having a body at all

Because a custom body is served verbatim rather than re-encoded, a scenario can return things a well-behaved API never would:

  • Truncated JSON — {"items": [{"id": 1 — the client's parser has to cope with a response that starts valid and stops mid-structure
  • An empty response — a 200 with nothing in the body at all
  • An error shape from a real gateway — whatever HTML or XML your CDN actually returns when it fails, rather than tidy JSON

Presets for the common ones (server error, service unavailable, gateway timeout, rate limited, truncated JSON, empty response, connection reset) are available from the scenario's Preset menu.

Every request that chaos breaks carries an X-MockBase-Chaos: true header, so a test can tell an injected failure apart from a real one — except a connection-reset scenario, which is discussed on its own below, since a dead connection carries no headers your client will ever get to read.

Reset connection

Check Reset connection on a scenario and the response stops being a message with a status code and a body — instead, the client sees a response start (your chosen status line and headers go out normally) and then the connection dies before any body arrives. No final chunk, no complete Content-Length, just a socket that closes mid-transfer. curl reports this as transfer closed with outstanding read data remaining; most HTTP client libraries raise a connection or incomplete-read error rather than handing back a response object at all.

This is a different failure shape than every other scenario type, and it's worth reaching for specifically because of that difference: a truncated-JSON body is still a complete HTTP response that a client fully receives and then fails to parse. A reset connection is a client that never gets to the parsing step — it's what a crashed backend process, a load balancer that gave up on a slow upstream, or a killed container actually look like on the wire, and those are handled by completely different code paths (a fetch/axios rejection, a socket exception) than a bad status code or malformed JSON ever exercises.

Reset connection ignores a custom body — there's nothing to serve once the connection is going to die before a body would arrive, so the two options are mutually exclusive on one scenario (checking one hides the other in the UI). The status code you picked is still sent as part of the response that starts, for whatever it's worth to a client that will never finish reading it.

Fail the first N requests

The error rate above is a probability roll — good for simulating a generally flaky upstream, but not reproducible: run the same test twice and it might fail zero times or three. When what you actually need is "the client retries twice, then succeeds," every time, set Fail the first N requests instead (next to the rate slider). The first N requests to the route are forced to fail — using the same status code and scenarios as the rate-based failure above — after which the route responds normally, forever.

The two can be combined on one route: once the first N have failed deterministically, the probability rate (if any) still applies on top.

The count is tracked per route (by its method and path) using the same Redis-backed mechanism as Counters, but it's internal bookkeeping rather than a named counter you create, so it doesn't appear in the mock's Counters panel — and there's currently no way to reset it from the UI. Editing or re-saving the route does not reset it either; only giving the route a different path starts the count over.

Chaos vs. delay vs. rate limits

Several different, independent things:

  • Delay (the route's delay_ms) is free on every mock and just slows a response down — the response is still the one you configured.
  • Chaos (the probability rate, "fail the first N," and connection reset) is free on every mock too, and replaces the response with a failure.
  • Fail the first N is deterministic but front-loaded and one-shot: requests 1 through N fail, then it's done, unlike rate limiting below, which re-trips every window.
  • Rate limit simulation is also deterministic, but recurring: the Nth request in a window gets a 429, every window. Testing backoff needs the limit to trip on a known, repeatable request, which a random roll can't guarantee.

Turn on both delay and chaos and a chaotic request is slow and wrong, which is often exactly what a flaky-upstream test should look like.

Chaos isn't available on a stateful CRUD route — a stateful route's whole response is generated from stored data, so there's no "normal response" for chaos to replace.

What still isn't simulated

Connection reset covers "the response never completes" — the most common real-world connection fault. What's still out of reach on a hosted endpoint: a deliberately malformed chunk (a chunk-size line that lies about how many bytes follow, rather than simply stopping) needs writing raw, spec-violating bytes to the socket below the level MockBase's ASGI server exposes; and a connection refused before any bytes go out at all isn't meaningfully different from the endpoint being down, which isn't something a test needs a mock to simulate.

Using it

A 100% rate is useful for confirming an error path works at all. Something lower — 10-20% — is closer to simulating a genuinely flaky upstream, so you can see whether retries and backoff actually kick in under realistic conditions instead of failing outright on the first bad response. When you need a specific, repeatable failure count instead, use "fail the first N requests."