Using Response Overrides
Inspectr supports special headers that let you override the response behavior for a request. This is helpful when you’re testing edge cases, simulating failures, or customizing mock data on the fly.
This guide covers how to use response override headers and what they do.
When to Use Overrides
Section titled “When to Use Overrides”- Simulate network latency
- Force specific HTTP status codes (e.g. 404, 500)
- Choose a specific example in your OpenAPI spec
- Override the Content-Type of a response
Overrides work in:
- Mock mode (with
--mock-backend) - Catch mode (with
--catch=true)
Supported Headers
Section titled “Supported Headers”| Header | Description |
|---|---|
inspectr-response-status | Override the HTTP status code (e.g. 404, 503) |
inspectr-response-delay | Delay response in milliseconds (e.g. 2000 = 2s delay) |
inspectr-response-example | Return a specific OpenAPI example by name |
inspectr-response-content-type | Override the Content-Type header in the response |
inspectr-tag | Tag a request with one or more values (e.g. billing, user:123) |
Example: Simulate Downtime
Section titled “Example: Simulate Downtime”curl http://localhost:8080/api/items \ -H "inspectr-response-status: 503" \ -H "inspectr-response-delay: 3000"This simulates a 3-second server outage with a 503 Service Unavailable status.
Example: Return a Named OpenAPI Example
Section titled “Example: Return a Named OpenAPI Example”Your OpenAPI spec includes this:
examples: validList: summary: A list of valid items value: items: ["A", "B", "C"] emptyList: summary: An empty list value: items: []Use this header to select emptyList:
curl http://localhost:8080/api/items \ -H "inspectr-response-example: emptyList"Example: Override Status Code Only
Section titled “Example: Override Status Code Only”curl http://localhost:8080/api/submit \ -H "inspectr-response-status: 404"This returns a 404 Not Found response regardless of the mock or catch behavior.
Example: Change Content-Type
Section titled “Example: Change Content-Type”Force a different Content-Type in the response:
curl http://localhost:8080/echo \ -H "inspectr-response-content-type: text/plain"Example: Tag a Request
Section titled “Example: Tag a Request”Apply simple or key/value tags that downstream tooling can read:
curl http://localhost:8080/api/items \ -H "inspectr-tag: billing, user:123"You can send multiple inspectr-tag headers to attach several tags to the same request, or use the key:value pattern for structured tagging.
When to tag requests
Section titled “When to tag requests”As you collect responses or webhooks, tags give you lightweight metadata that can help you bundle and mark operations, giving them additional context. These tags can be used for filtering in the history and for statistic insights.
Some use-cases:
- QA test runs – Mark exploratory sessions (e.g.
inspectr-tag: qa:test-run-42) so logs and analytics are easy to filter when triaging bugs. - Environment targeting – Compare request data and how the API services behave differently (e.g.
inspectr-tag: env:staging) between dev/staging/prod environments. - Version tracking – Capture which app or API version triggered the request (e.g.
inspectr-tag: client-version:2.3.1) when validating compatibility.
The `inspectr-tag” is never forwarded to the connected service, so your requests stay untouched. It is a powerful option to use for observability use-cases, comparing statistics on the dashboard or reviewing the request history with the extra context.
Summary
Section titled “Summary”Response overrides help you simulate different scenarios without changing your backend or OpenAPI file. They’re great for testing, mocking, and QA validation workflows.