Chaos Testing — Inject HTTP Errors Into Mock APIs

// What is Chaos Testing?

In a perfect world your API always returns 200 OK. In production, it doesn't. Rate limits kick in. Servers go down. Records aren't found. Chaos Testing lets you simulate all of this against your mock API so your frontend UI is tested against failure states — not just happy paths.

// How It Works

When Chaos Mode is enabled on a Mock API, every incoming request is intercepted before any routing logic. A random number is rolled against your configured error rate. If the roll hits, one of your enabled error codes is chosen at random and returned immediately — with an X-Chaos-Injected: true header so your tooling can distinguish injected errors from real ones.

// Configuring Chaos Testing

Open any Mock API editor and click the Chaos button in the top-right toolbar. The chaos panel opens in the right sidebar.

// Available Error Codes

The following error codes are available for all Mock APIs. Each has a pre-built JSON response body. For Import YAML APIs, spec-defined error shapes from your OpenAPI document are automatically pulled in and tagged with a spec badge.

// Spec-Defined Error Shapes (Import YAML)

When your Mock API was created from an OpenAPI spec (Import YAML), the Chaos panel automatically imports the error response schemas defined in your spec. For example, if your spec defines a 404 response for GET /pet/{petId}with a specific JSON shape, that shape is used verbatim — not a generic fallback. These entries are tagged with a purple spec badge.

paths:
  /pet/{petId}:
    get:
      responses:
        "200":
          description: successful operation
        "400":
          description: Invalid ID supplied
        "404":
          description: Pet not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              example:
                code: 404
                type: error
                message: "Pet not found"

When a chaos-injected 404 fires, the response body will be exactly{ code: 404, type: "error", message: "Pet not found" } — not a generic error object.

// Detecting Injected Errors

Every chaos-injected response includes an X-Chaos-Injected: true response header. Use it in your tests to filter out injected errors from real ones, or to assert that your app correctly handles the error regardless of origin.

const response = await fetch('/api/invoke/mock/pet-store/pets');

if (response.headers.get('X-Chaos-Injected') === 'true') {
  // This was a chaos-injected error — expected during chaos testing
  expect(response.status).toBeGreaterThanOrEqual(400);
} else {
  // Normal response — assert business logic
  expect(response.status).toBe(200);
}

// Best Practices

• ›
  Start at 10–20% rate — A low rate lets you exercise error paths without making every page interaction painful. Ramp up only for dedicated resilience sessions.
• ›
  Enable only relevant codes — For a read-only dashboard, 404 and 500 are the most useful. For a form-heavy app, add 400, 409, and 422.
• ›
  Disable before demos — Remember to toggle Chaos off before a live demo. The Chaos button turns orange when active — a visible reminder.
• ›
  Check X-Chaos-Injected in E2E tests — If your Playwright/Cypress suite calls mock APIs, filter on this header so chaos errors don't cause false test failures.
• ›
  Use 100% rate to force a specific error — Set rate to 100% and enable only one error code to reproduce a specific failure scenario every single time.