Every response FlowMock's proxy returns carries a small set of public x-flowmock-* headers describing what happened to it. Open devtools on any proxied request and they're right there - no need to leave your app and go find the request in Traffic.

The headers

Header	Set when	Value
`x-flowmock-mode`	Always	`mock` \| `upstream` \| `error`
`x-flowmock-rule-id`	A mock matched and owns the response body/status	the rule id
`x-flowmock-transforms`	One or more transforms mutated the body	a positive integer count
`x-flowmock-scenario-id`	A scenario is active on the bind for this request	the scenario id
`x-flowmock-delay-ms`	An injected delay greater than zero was applied	the delay, in milliseconds

x-flowmock-mode is on every proxied response. The other four are presence signals - they're set only when they apply, and never sent as 0, false, or empty. A quiet pass-through where FlowMock changed nothing carries x-flowmock-mode: upstream and none of the other four.

These headers are stamped last, after any mock or upstream response headers have been copied onto the outgoing response - a mock author can't fake x-flowmock-mode: mock (or point you at the wrong rule id) by setting the same header names in a mock's authored headers.

Reading a response

A mock served the body:

http

x-flowmock-mode: mock
x-flowmock-rule-id: ovr_a1b2c3

The response body and status came from that rule, in full.

The real API answered, with injected latency:

http

x-flowmock-mode: upstream
x-flowmock-delay-ms: 800

This is your staging API's real response. FlowMock held it for 800ms before releasing it - that's simulated latency, not a slow upstream.

A transform patched a live upstream response:

http

x-flowmock-mode: upstream
x-flowmock-transforms: 2

Still upstream - the body came from your real API, then two transform rules mutated fields on it. This is not a mock: nothing replaced the response wholesale, so x-flowmock-rule-id is absent.

A delay-only override: if the only override active for a request injects delay and doesn't replace the body, the response reports x-flowmock-mode: upstream plus x-flowmock-delay-ms - never mock. Mode tracks who owns the response body, not "did FlowMock touch this request at all."

FlowMock failed, not your API:

http

x-flowmock-mode: error

A 500 with x-flowmock-mode: error is FlowMock's own failure (for example, a mock referencing a file asset that couldn't be served) - not your upstream returning a real 500. An upstream error response still reports x-flowmock-mode: upstream.

Reading headers from page JS

The headers are ordinary response headers - read them from fetch like any other:

const res = await fetch("/api/widgets/1");
const mode = res.headers.get("x-flowmock-mode");
const ruleId = res.headers.get("x-flowmock-rule-id");

For a cross-origin request (page JS reading a response that came back through the FlowMock proxy on a different origin) the browser only exposes headers listed in Access-Control-Expose-Headers. FlowMock lists its five header names there on every response.

If your upstream API already exposes its own headers to page JS, FlowMock merges its names into that list rather than replacing it - an app that's already reading its own headers cross-origin keeps working after pointing at FlowMock. This also holds for credentialed requests (fetch(url, { credentials: "include" })): even if your upstream exposes headers via *, FlowMock appends its names explicitly, because the Fetch standard treats * as a literal header name rather than a wildcard once credentials are involved.

What's not in this contract

x-flowmock-log-* and x-flowmock-internal-* headers exist internally for log correlation, but they are private - stripped from every response before it leaves the proxy edge. They never reach a client and are not part of this contract. Don't build against them; the five x-flowmock-* names above are the whole public surface.

Traffic - the full request/response history these headers summarize
Mocks and overrides - what sets x-flowmock-rule-id and x-flowmock-delay-ms
Transforms - what sets x-flowmock-transforms
Scenarios - what sets x-flowmock-scenario-id

The headers

Reading a response

Reading headers from page JS

What's not in this contract

Related