> This page is for Postman Docs, version Latest (v12) (default).
> For other versions, use one of these documentation indexes:
> - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt
> - v11: https://learning.postman.com/v11/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt.

# Apply behaviors to mocks that mimic slow or failing dependencies

> Add scenarios to model what a mock returns, and apply behaviors like latency, errors, and rate limits to test how your service handles failures.

A [mock](/docs/design-apis/mock-apis/mocks/overview) can contain multiple scenarios. Each scenario bundles its own request handling code with its own behaviors, the real-world faults like latency, errors, and rate limits you layer on top. Use scenarios to model the different situations your API might encounter and to test how your service handles a struggling dependency.

## Manage scenarios in a mock \[#manage-scenarios-in-a-mock]

A *scenario* is a named variant of your mock that bundles its own request handling code and endpoints with its own [behaviors](#apply-behaviors-to-a-scenario), the real-world faults like delays and errors layered on top. Because all of a mock's scenarios share the same mock URL, you can use scenarios to test different situations against a single mock, such as a standard request flow and a degraded flow under heavy load, without creating a separate mock for each one.

A scenario has two layers that work independently:

* [**Code**](/docs/design-apis/mock-apis/mocks/customize-a-mock#customize-your-mock) — The request handling logic that defines what the scenario does, including its endpoints, response bodies and status codes, and any state it keeps across requests. This is the functional logic of the dependency you're mocking. For example, one scenario might return a full list of items from an endpoint, while another returns an empty list.
* [**Behaviors**](#apply-behaviors-to-a-scenario) — The real-world faults layered on top of the code, like latency, errors, and rate limits. They change how the scenario responds under stress without changing what it returns. For example, you can add a delay to test how your service handles a slow dependency.

You can apply behaviors to a scenario directly in the mock, or reuse a scenario in a [simulation](/docs/design-apis/simulate-conditions/overview) and override its behaviors for a specific run. To learn more, see [Apply scenarios and behaviors](/docs/design-apis/simulate-conditions/apply-scenarios-to-a-simulation).

Every mock starts with a **default** scenario. Scenarios appear as tabs in the mock editor. When you start the mock and send requests to it, it uses the default scenario. To run a different scenario, add the mock to a [simulation](/docs/design-apis/simulate-conditions/create-a-simulation) and select the scenario there.

You can run a mock and its scenarios locally from the app or with the Postman CLI ([`postman mock run`](/docs/postman-cli/postman-cli-mock#postman-mock-run)). Send the `x-mock-scenario` header to choose a scenario other than the default.

## Create a scenario \[#create-a-scenario]

1. Click the ![Items icon](https://assets.postman.com/postman-docs/aether-icons/v12/descriptive-items-stroke.svg#icon) **Items** tab in the sidebar.
2. Click **Mocks**.
3. Select the mock you want to add a scenario to.
4. In the mock editor, click ![Add icon](https://assets.postman.com/postman-docs/aether-icons/v12/action-add-stroke.svg#icon) **Add new scenario** next to the scenario tabs.
5. Enter a name for the scenario.

The new scenario is based on the [default scenario](#the-default-scenario). In the **Code** pane, define the request handling logic for the scenario. Each scenario has its own code, so you can customize how it handles requests independently of other scenarios. To learn more, see [Customize your mock](/docs/design-apis/mock-apis/mocks/customize-a-mock#customize-your-mock).

To target a specific scenario in a request, include the `x-mock-scenario: <scenario-name>` header. In the **Code** pane, click ![Open in Postman icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-action-openInPostman-stroke.svg#icon) **Open in a new request** next to the header key-value to open a new request with the header already filled in.

## The default scenario \[#the-default-scenario]

Click a scenario's tab to view and edit its code and behaviors. One scenario in the mock is the *default*, marked with `default: true` in the `config.yaml` file. When you start the mock directly, it uses the default scenario, including any behaviors applied to it.

To run a specific scenario with behaviors applied, add the mock to a [simulation](/docs/design-apis/simulate-conditions/create-a-simulation) and use the **Select scenario** dropdown list to choose the scenario you want. To learn more, see [Apply mock scenarios to a Postman simulation](/docs/design-apis/simulate-conditions/apply-scenarios-to-a-simulation).

## Apply behaviors to a scenario \[#apply-behaviors-to-a-scenario]

Apply *behaviors* to a scenario to introduce real-world disruptions like latency, errors, and rate limits. Behaviors saved on a scenario are its permanent failure profile. They define what the scenario represents, such as a slow dependency or a service returning errors, and can be reused across tests. Behaviors are available when you [add the scenario to a simulation](/docs/design-apis/simulate-conditions/apply-scenarios-to-a-simulation), where you can override them for a specific run without changing the scenario itself. To test how your service responds when multiple dependencies fail at the same time, use a [simulation](/docs/design-apis/simulate-conditions/overview) to coordinate multiple mocks together.

In the mock's `config.yaml` file, behaviors are stored under the scenario's `conditions` key.

1. Click the scenario tab you want to apply behaviors to.
2. In the mock editor toolbar, click ![Manage icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-descriptive-manage-stroke.svg#icon) **Configure**.
3. Turn on each behavior you want to apply, then enter a value where required:

   * **Simulate error response** — Return a specified HTTP status code.
   * **Add response delay** — Add a delay in milliseconds before the scenario sends a response, to mimic network latency.
   * **Simulate rate limiting** — Limit the scenario to a maximum number of requests per minute. Requests over the limit receive a `429 Too Many Requests` response.
   * **Chaos mode** — Randomly fail a percentage of requests with 5xx status codes.

> **Warning**
>
> If you turn on both **Simulate error response** and **Chaos mode**, and the error response is a 5xx status code (such as `502`), Chaos mode only returns that specific 5xx error. To test a range of 5xx failures, use either **Simulate error response** or **Chaos mode**, not both.

The scenario shows how many behaviors are applied, along with the value for each, such as `2000 ms`.

To learn how a scenario's behaviors are reused and overridden in a simulation, see [Apply mock scenarios to a Postman simulation](/docs/design-apis/simulate-conditions/apply-scenarios-to-a-simulation).