Faults
A fault makes a mock misbehave on purpose, so you can see what your client does when the other side is slow, down, rate limited or sends something broken. Faults belong to an endpoint: open it and choose the Faults tab, then Add a fault.
What a fault can do
| Fault | What the client sees |
|---|---|
| Slow response | The answer arrives after a delay you choose (a fixed time, or a range). Delays add up when an endpoint has several. |
| Error | A status from 400 to 599 (503 by default), with the headers and body you give it. |
| Dropped connection | The connection is closed without an answer, immediately or after a time. |
| Cut-off response | The right status and headers, but the body stops partway. |
| Slow transfer | The body arrives at a speed you choose, in bytes per second. |
| No answer | The request is accepted and never answered, so a client’s timeout is tested. |
| Broken response | The right status with a body that cannot be parsed: invalid JSON, empty, or an HTML error page. |
| Rate limit | 429 with Retry-After once there are too many requests in a window, with X-RateLimit-* headers. It can count per API key. |
| Custom (a script) | JavaScript decides what happens to each request. See below. |
The first error, rate limit, dropped connection or missing answer replaces the response, so the scenario does not run: no state is changed and no callback is sent. The endpoint’s Test tab says it does not apply faults, and Traffic records which fault answered.
Which requests a fault applies to
- A share of requests: 20% by default, or any chance you set.
- By count: every 3rd request, the first 3, or everything after the first 5. Retry and circuit-breaker tests then behave the same every time.
- Only when asked: add a condition such as a header (
x-chaos: error), so only the requests a test marks are affected and everything else is normal.
Counting starts when the mock starts. On the Faults tab, Start counting again makes “every 3rd”, “the first 3”, rate limits and what custom scripts remembered start from zero on the running mock, without restarting it.
Ready-made situations
The Add a fault menu has four: Slow 3G, Flaky mobile connection, Fails 3 times then works (a client that retries gets through on the fourth) and Goes down after 5 requests (for testing a circuit breaker).
Write your own
Choose Custom (a script). A short JavaScript runs for every request and decides what happens:
// Fail every 4th request with a 503
if (fault.count % 4 === 0) {
fault.fail(503, { error: 'try again later' })
}fault.delay(ms), fault.fail(status, body), fault.drop(), fault.hang(), fault.corrupt(), fault.truncate() and fault.throttle() are the actions. fault.count is how many requests the fault has seen, and fault.memory is kept between requests, so a script can write an outage that comes and goes, a quota per API key, or a slowdown that grows. The editor suggests names as you type, and Start from an example offers seven working scripts.
Like other scripts, a custom fault needs the project to be trusted (the Trust scripts button, or zyvra trust). A script that fails answers 500 with the reason instead of being ignored.