Skip to documentation

Guide · Conditional responses

Available

Keep every important branch visible

A conditional response is a complete response contract selected by an expression. Use it for domain outcomes such as missing data or invalid input; use Faults for transport-level breakage.

In this guide

  • Separate success and error contracts
  • Use request and state conditions consistently
  • Avoid hidden special-case response modes
  • Prove every branch in the tester

Prerequisites

  • A DotMock workspace you can access
  • The API ID in $API_ID and its published runtime URL in $MOCK_URL when the example calls the mock
On this page
  1. A condition selects a full response
  2. Use conditions for domain outcomes
  3. Return the same error shape your client expects
  4. Do not use an application response to fake a broken connection
  5. Prove one branch at a time

A condition selects a full response

Each enabled conditional has an expression plus status, headers, body, and optional schema. The endpoint default is the fallback when no condition wins. Keep the short expression and returned status visible in the collapsed row.

Use conditions for domain outcomes

Read params, query, lowercase header keys, parsed body fields, workspace-local hour, and state. Combine comparisons with &&, ||, and !.

Unknown user
!state.exists("users-by-id", params["userId"])

Invalid request
body.quantity <= 0 || body.quantity > 100

Plan requirement
header["x-plan"] != "pro"

Business hours
hour < 9 || hour >= 17

Return the same error shape your client expects

Choose a meaningful status and JSON body for each branch. Reuse a shared error model when the real API has a stable envelope; otherwise keep a small branch-specific schema rather than inventing one universal error.

404 response
{
  "message": "User not found",
  "code": "USER_NOT_FOUND"
}

Do not use an application response to fake a broken connection

A 503 JSON body is still a valid HTTP response. To test a timeout, delayed body, disconnect, malformed payload, or upstream failure, configure the endpoint Faults section. This keeps transport behavior distinct from domain rules.

Prove one branch at a time

Start with a request that reaches the default. Change only the value that should activate one condition, run safely, and verify the selected status/body/headers. For state-aware rules, inspect the proposed diff or seed a known live value before the request.