Docs / Building

Mock servers

Stand up endpoints that return whatever you need — to unblock work, pin a contract, or simulate failures you cannot reproduce on demand.

Creating one#

Open Build → Mock Servers and press New.Name it; it gets a public URL under /m/<slug>.
Add a rule.A method, a path, a status code, and a response body. GET /orders returning 200 and a JSON array, say.
Call it.The URL works immediately — there is no process to start or port to pick.

Matching rules#

Rule path	Matches
`/orders`	Exactly that path
`/orders/:id`	`/orders/42` — but not `/orders/42/items`
method `ALL`	Any method on that path

When two rules could answer, the higher priority wins. Use that to add a specific case above a general one.

Simulating failures#

This is the use that repays the effort most and is most often skipped. You cannot ask a payment provider to return 503 on demand — you can point your app at a mock that always does.

POST /charge → 503, to find out whether your retry logic retries
A rule with a long delay, to find out whether your timeout is set
A 200 with a field missing, to find out whether your parser copes
429 with a Retry-After header, to exercise backoff

Worth doing once

Most teams discover their error handling was never actually exercised. This is the cheapest way to find out.

Seeing what arrived#

Each mock keeps a log of the requests it answered — method, path, headers and body — which is the quickest way to check what a client is really sending. Sensitive headers are redacted and bodies are truncated.

Frequently asked questions#

How do I create a mock API endpoint?

Create a mock server, add a rule with a method, path, status code and response body, and call the URL it is given. Nothing needs starting or deploying.

Can a mock server return an error to test my error handling?

Yes. Set the rule's status code to 500, 503 or 429 and it will return that every time, which is how you exercise retry and fallback paths you cannot otherwise trigger.