Docs menu · Fault injection
APIMock documentation
Fault injection
Real APIs go down, slow down and return odd data. Fault injection makes your mock do the same on purpose, so you can check that your app shows an error message, retries sensibly and keeps its loading states honest before production tests it for you.
Updated
Quick start
- Create at least one endpoint. Faults change the responses of existing endpoints.
- Open Faults in the app sidebar and pick a preset such as Flaky upstream, or Custom rule. Check the path, method and duration in the dialog, then click Add rule.
- Use Try it on the same page to send a request and see the fault, or call the endpoint from your app.
- Check Request History. Injected requests carry an amber
faultbadge.
What can break
| Fault | Kind | Effect |
|---|---|---|
| Error status | status | Returns a 4xx or 5xx instead of the endpoint's response, optionally with Retry-After. |
| Latency | latency | Adds a delay (up to 30 s), with optional ± jitter and occasional spikes. |
| Null fields | nullify | Each JSON field has a chance of becoming null. id is never touched. |
| Drop fields | drop_field | Each JSON field has a chance of being removed. id is never touched. |
| Empty lists | empty | List responses come back as []. Single objects pass through unchanged. |
Payload faults (null fields, drop fields, empty lists) only apply to JSON responses. Resource envelopes keep their { data, meta } shape; only data is damaged, and resource error responses are left readable.
Which requests a rule affects
- Path pattern is the path after your mock URL.
*matches any characters, including/./*is every path. - Route parameters are not understood. An endpoint at
/users/:idis matched with/users/*. The path field suggests patterns for your endpoints. - Method narrows a rule to one HTTP method. Leave it on Any method to match all of them.
- Chance per request is how often a matching request is hit. 100% means every time. Lower values are useful for testing retries, but a single test request may come back normal.
- A request to a path with no endpoint still returns 404. Error-status faults replace an endpoint's response before auth checks or request validation run.
When several rules match
- At most one error status applies: the first matching rule whose chance comes up.
- Delays from every matching latency rule add up, capped at 30 seconds.
- For null and dropped fields, the highest chance among the matching rules is used.
One request at a time
For automated tests, send the X-APIMock-Fault request header. It applies to that request only, ignores workspace rules, and has no randomness in whether it fires: the same header gives the same fault every run. Combine directives with commas.
| Header value | Effect |
|---|---|
| 503 | Return 503 (any code from 400 to 599) |
| 429;retry-after=2 | Return 429 with Retry-After: 2 |
| latency=3000 | Wait 3000 ms before responding |
| nullify=0.2 | Each field has a 20% chance of becoming null |
| drop_field=0.2 | Each field has a 20% chance of being removed |
| empty | Return empty lists |
| none | Ignore every workspace rule for this request |
curl -i -H "X-APIMock-Fault: 503" https://<your-workspace>.<host>/orders
curl -i -H "X-APIMock-Fault: latency=3000, nullify=0.2" https://<your-workspace>.<host>/ordersA malformed header returns 400 with an X-APIMock-Fault-Error header explaining the problem, so a typo fails your test instead of quietly passing.
Spotting injected responses
- Every injected response carries an
X-APIMock-Faultresponse header listing what was applied, e.g.status=503, latency=2000. Status faults with Retry-After also send aRetry-Afterheader. - Both headers are exposed to browser code when the endpoint allows CORS from any origin.
- Request History marks injected requests and can filter to show only them.
Expiry and safety
- Every rule switches itself off: after one hour by default, and never more than seven days out. +1h adds an hour without turning a rule back on.
- While any rule is active, every app page shows a banner and the Faults sidebar link shows a count, so teammates in the workspace know the failures are deliberate.
- Clear all deletes every rule in the workspace and the mock responds normally again.
From an AI agent
The APIMock MCP server exposes set_fault_rule, list_fault_rules and clear_fault_rules, so a coding agent can break the mock, check your app's error handling, and clean up afterwards. Rules created this way show up on the Faults page like any other. See MCP server to connect an agent.