---
title: "Arm a fault"
method: POST
path: "/v1/runs/{runId}/faults"
tags: ["Faults"]
---

# Arm a fault

`POST /v1/runs/{runId}/faults`

## Request

- Base URL: `https://api.ironfang.com/rig`
- URL: `https://api.ironfang.com/rig/v1/runs/{runId}/faults`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Arms deterministic interference on one resource of an active run. `delay`, `duplicate` and `drop` act on the forwarding of a callback resource that has a connector route: the delivery is held for the duration, made `copies` extra times, or recorded and never forwarded. `status_override` makes a `mock_http` resource answer the given status whatever its rules said, body and headers unchanged. A fault fires on the next observation it applies to, `count` times (default once) or, if `persistent`, until removed or the run ends; every firing is a `fault.injected` event beside the observation it acted on. One active fault of each type per resource. Needs rig.run. No randomness: the same faults against the same traffic give the same timeline.

## Request body

- FaultSpec: Deterministic interference on one resource. delay, duplicate, drop, reorder and payload_mutation act on the forwarding of a callback with a connector route; status_override, connection_reset, bandwidth_limit and partial_response act on a mock's answer. Each type takes its own parameter and no other.
  - `batch` integer: For reorder: how many deliveries to hold before releasing them last-first. A batch left incomplete when the run ends expires with outcome held.
  - `bytes` integer: For partial_response: how much of the body the mock sends before closing the connection; 0 sends the headers alone.
  - `bytes_per_second` integer: For bandwidth_limit: the rate the mock sends its body at. Raised, and recorded as capped, if the body would otherwise take longer than 30s.
  - `copies` integer: For duplicate: extra deliveries; default 1.
  - `count` integer: How many times the fault fires before it is spent; default 1. A reorder fires once per released batch.
  - `delay` string: For delay: a duration such as "500ms" or "5s", at most 30s.
  - `mutations` Mutation[]: For payload_mutation: the changes made to the forwarded body, in order. The received body stays on the timeline untouched; the body sent is the payload of the fault.injected event.
    - `bytes` integer: For truncate: how many bytes to keep.
    - `find` string: For replace: the text to find.
    - `op` 'set' | 'remove' | 'replace' | 'truncate', required
    - `path` string: For set and remove: a JSON Pointer such as "/customer/email" or "/items/0"; "" names the whole body, "-" appends to an array.
    - `replace` string: For replace: the text put in its place; may be empty.
    - `value` unknown
  - `persistent` boolean: Fire on every observation until removed; count is then not given.
  - `resource` string, required: The resource, by the name the suite gave it.
  - `status` integer: For status_override: the status to answer.
  - `type` 'delay' | 'duplicate' | 'drop' | 'status_override' | 'reorder' | 'payload_mutation' | 'connection_reset' | 'bandwidth_limit' | 'partial_response', required

## Response `201`

Fault armed

- object
  - `fault` Fault, required
    - `created_at` string, date-time, required
    - `created_by` string
    - `fired` integer, required
    - `id` string, uuid, required
    - `organisation_id` string, uuid, required
    - `remaining` integer: Firings left; absent when persistent.
    - `removed_at` string, date-time
    - `resource` string, required
    - `resource_id` string, uuid, required
    - `run_id` string, uuid, required
    - `spec` FaultSpec, required: Deterministic interference on one resource. delay, duplicate, drop, reorder and payload_mutation act on the forwarding of a callback with a connector route; status_override, connection_reset, bandwidth_limit and partial_response act on a mock's answer. Each type takes its own parameter and no other.
      - `batch` integer: For reorder: how many deliveries to hold before releasing them last-first. A batch left incomplete when the run ends expires with outcome held.
      - `bytes` integer: For partial_response: how much of the body the mock sends before closing the connection; 0 sends the headers alone.
      - `bytes_per_second` integer: For bandwidth_limit: the rate the mock sends its body at. Raised, and recorded as capped, if the body would otherwise take longer than 30s.
      - `copies` integer: For duplicate: extra deliveries; default 1.
      - `count` integer: How many times the fault fires before it is spent; default 1. A reorder fires once per released batch.
      - `delay` string: For delay: a duration such as "500ms" or "5s", at most 30s.
      - `mutations` Mutation[]: For payload_mutation: the changes made to the forwarded body, in order. The received body stays on the timeline untouched; the body sent is the payload of the fault.injected event.
        - `bytes` integer: For truncate: how many bytes to keep.
        - `find` string: For replace: the text to find.
        - `op` 'set' | 'remove' | 'replace' | 'truncate', required
        - `path` string: For set and remove: a JSON Pointer such as "/customer/email" or "/items/0"; "" names the whole body, "-" appends to an array.
        - `replace` string: For replace: the text put in its place; may be empty.
        - `value` unknown
      - `persistent` boolean: Fire on every observation until removed; count is then not given.
      - `resource` string, required: The resource, by the name the suite gave it.
      - `status` integer: For status_override: the status to answer.
      - `type` 'delay' | 'duplicate' | 'drop' | 'status_override' | 'reorder' | 'payload_mutation' | 'connection_reset' | 'bandwidth_limit' | 'partial_response', required
    - `status` 'active' | 'spent' | 'removed', required
    - `type` 'delay' | 'duplicate' | 'drop' | 'status_override' | 'reorder' | 'payload_mutation' | 'connection_reset' | 'bandwidth_limit' | 'partial_response', required

## Other responses

- `400`: The body is not one strict JSON value of the documented shape (`invalid_json`).
- `401`: No credential, an invalid one, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, or names another organisation (`forbidden`, `insufficient_scope`).
- `404`: No such object in this organisation (`not_found`).
- `409`: The run has ended, or an active fault of that type is already armed on the resource
- `422`: A field is invalid; the message names it (`invalid_request`).
- `429`: The run has its limit of faults

---

[API](https://skmtc.dev/ironfang/apis/ironfang-rig-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-rig-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-rig-api/revisions/3e86a312dad1?raw)