Operation Modes

Inspectr can operate in four simple modes depending on what you’re trying to do:

• Backend – forward traffic to a real backend
• Catch – accept and capture requests without forwarding
• Mock – respond using OpenAPI-based mock responses
• Mirror – instantly echo requests back to the caller

Each mode solves a different problem, but all of them give you the same thing: full visibility into real HTTP traffic without reconstructing behavior from logs.

This guide explains each mode with:

• a minimal .inspectr.yaml
• a runnable curl example
• an example HTTP response
• what you’ll see inside Inspectr

---

How Inspectr decides what to do

When a request arrives, Inspectr chooses a response strategy based on your configuration:

• If a backend is configured, requests are forwarded
• If mockBackend is configured, Inspectr generates a response from OpenAPI
• If mirror is enabled, Inspectr echoes the request back immediately
• If catch is enabled (or no backend is configured), Inspectr returns 200 OK

You can always keep the UI enabled (app: true) to inspect traffic in real time.

See also:

View configuration options →

---

Backend mode

Backend mode is the default Inspectr workflow when you need full visibility into a real API.

Inspectr sits transparently between your client and backend:

1. The client sends requests to Inspectr
2. Inspectr forwards them to your backend
3. The backend response is returned unchanged
4. Inspectr captures the full exchange for inspection

When to use backend mode

Use backend mode when you want to:

• debug real backend behavior without changing client code
• inspect headers, payloads, status codes, and errors
• analyze latency and response timing
• observe production-like traffic locally or in CI
• troubleshoot issues that only show up at runtime

Backend mode is ideal when your backend already exists and you need visibility, not simulation.

Learn how to debug real API traffic with Inspectr.

Follow the guide →

---

Config

.inspectr.yaml

backend: "http://localhost:3000"

# Other options as example
app: true
appPort: "4004"
print: true

Example request

curl -i http://localhost:8080/hello

Example response (from backend)

HTTP/1.1 200 OK
Content-Type: application/json

{"message":"hello from backend"}

What you’ll see in Inspectr

• Captured operation: GET /hello
• Full request & response (headers + body)
• Status code and timing information

---

Catch mode

Catch mode accepts requests and captures them — without forwarding them anywhere.

Inspectr always responds with a default 200 OK, making it safe to expose as a temporary or exploratory endpoint.

When to use catch mode

Catch mode is ideal when you:

• need an instant webhook endpoint
• want to inspect real payloads from third-party systems
• are exploring an undocumented or evolving integration
• need to test how senders/clients behave when responses vary (status codes, content types)
• want to capture traffic before implementing backend logic

Catch mode captures incoming requests and returns a configurable response without forwarding them to a backend.

Testing error and edge cases in catch mode

Catch mode is not limited to returning a simple 200 OK. You can control how Inspectr responds on a per-request basis using Inspectr-specific directives.

This makes catch mode extremely useful for testing unhappy paths and client-side error handling, without changing your backend or writing custom mocks.

Inspectr supports the following response directives:

• inspectr-response-status – override the HTTP status code
• inspectr-response-content-type – override the Content-Type header

These directives can be sent as headers or embedded as metadata, depending on your setup.

Example: Simulating client error handling

Force a client-side validation error:

curl -i -X POST http://localhost:8080/webhook \
  -H "inspectr-response-status: 400" \
  -H "content-type: application/json" \
  -d '{"invalid":true}'

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"status":"Bad Request"}

Example: Testing retry and backoff logic

Simulate rate limiting or temporary failures:

curl -i -X POST http://localhost:8080/webhook \
  -H "inspectr-response-status: 429" \
  -H "inspectr-response-content-type: application/json"

Response:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{"status":"Too Many Requests"}

This allows you to validate:

• retry behavior
• backoff strategies
• error parsing and surfacing in the UI

Example: Verifying content-type handling

Test how your client behaves with unexpected or legacy content types:

curl -i -X POST http://localhost:8080/webhook \
  -H "inspectr-response-status: 500" \
  -H "inspectr-response-content-type: text/plain"

Response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

Internal Server Error

This is useful when validating:

• strict JSON parsers
• fallback logic
• error rendering for non-JSON responses

By combining request capture with controlled responses, catch mode becomes a powerful tool for exercising edge cases and validating client robustness.

See how Inspectr simplifies webhook debugging.

Explore the how-to →

Config

.inspectr.yaml

catch: true

# Other options ...

Example request

curl -i -X POST http://localhost:8080/webhook \
-H "content-type: application/json" \
-d '{"type":"ping","id":"evt_123"}'

Example response

HTTP/1.1 200 OK
Content-Length: 0

What you’ll see in Inspectr

• Captured operation: POST /webhook
• Full payload for inspection and replay
• A clean baseline for overrides (status codes, delays, failures)

---

Mock mode

Mock mode lets Inspectr respond without a backend, using an OpenAPI document as the source of truth.

Responses can be static examples from your spec or dynamically generated based on schemas.

When to use mock mode

Use mock mode when:

• the backend doesn’t exist yet
• you’re developing frontend or client code first
• you want deterministic responses for testing
• you’re validating client behavior against an API contract
• you want to test error cases without backend changes

Mock mode is ideal for contract-first development and fast iteration.

Learn more about OpenAPI-based mocking in Inspectr.

Read up on all the mocking options →

Config (static mocking)

.inspectr.yaml

mockBackend: "./openapi.yaml"

# Other options...

Example OpenAPI snippet

openapi.yaml

paths:
  /items:
    get:
      responses:
        "200":
          description: Success
          content:
            application/json:
              examples:
                default:
                  value:
                    items: ["A", "B", "C"]

Example request

curl -i http://localhost:8080/items

Example response (static)

HTTP/1.1 200 OK
Content-Type: application/json

{"items":["A","B","C"]}

Config (dynamic mocking)

.inspectr.yaml

mockBackend: "./openapi.yaml"
mockDynamic: true

Example response (dynamic)

HTTP/1.1 200 OK
Content-Type: application/json

{"items":["KqTzL","p9aV2","mR1xQ"]}

What you’ll see in Inspectr

• Operation matched to OpenAPI path & method
• Generated response (static or dynamic)
• A clear link between spec and runtime behavior

Mirror mode

Mirror mode turns Inspectr into a request reflection endpoint.

Every incoming request is captured and immediately echoed back as the response — no backend involved.

When to use mirror mode

Mirror mode is perfect when you want to:

• see exactly what a client or webhook sender is transmitting
• debug headers, encoding, auth, and payload shape
• verify SDK or client behavior
• test connectivity from third-party systems
• remove backend behavior from the equation entirely

Unlike simple request mirrors, Inspectr also stores, replays, and exports every request.

Config

.inspectr.yaml

mirror: true

# Other options...

Example request

curl -i -X POST http://localhost:8080/webhook/test \
  -H "content-type: application/json" \
  -H "x-source: stripe" \
  -d '{
    "event": "payment.succeeded",
    "id": "evt_123",
    "amount": 4200
  }'

Example response (mirrored)

HTTP/1.1 200 OK
Content-Type: application/json

{
"event": "payment.succeeded",
"id": "evt_123",
"amount": 4200
}

What you’ll see in Inspectr

• Captured operation: POST /webhook/test
• Request headers and payload
• Immediate feedback loop for client debugging

Mode summary

Mode	Behavior	Best used for
Backend	Forward to backend and inspect	Debugging real APIs and responses
Mock	Respond from OpenAPI spec	Contract-first development and testing
Catch	Accept and store requests only	Webhooks and payload exploration
Mirror	Echo request back immediately	Client, SDK, and webhook debugging