> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Policy statuses, errors, and webhook events

> Policy and transaction statuses that policies produce, the errors the policy endpoints return, and the policy webhook events to subscribe to.

## Policy statuses

| Status | Meaning |
| - | - |
| `draft` | Not enforced. Editable. Also the status while an activation waits for quorum, and after one is rejected or expires. |
| `enforced` | The policy your organization evaluates every signing request against. At most one at a time. |
| `archived` | Previously enforced, then replaced. Read-only. |

## Activation response

[Activate policy](https://www.bitnob.dev/api-reference/platform/policies/activate-policy.md) returns `202 Accepted` with an approval request:

| Field | Meaning |
| - | - |
| `status` | Always `pending_authorization`. |
| `approval_request_id` | Matches the request in the dashboard and in webhook events. There is no endpoint to fetch it. |
| `required_approvals` | How many quorum approvals are needed. |
| `expires_at` | When the request lapses if it hasn't been approved. |
| `policy_id` | The policy being activated. Poll [Get policy](https://www.bitnob.dev/api-reference/platform/policies/get-policy.md) for its `status`. |
| `message` | A readable explanation of the next steps. |

## Transaction statuses a policy can produce

| Status | Set by | Terminal | Next |
| - | - | - | - |
| `pending_authorization` | `require_approval` | No | Signing once approved, or `rejected` |
| `delayed` | `delay` | No | Signing at `execute_at` |
| `rejected` | An approver | Yes | None |

All transaction statuses are listed in [Transaction lifecycle](https://www.bitnob.dev/docs/platform/core-concepts.md#transaction-lifecycle).

## Errors

| Endpoint | Status | Cause | Fix |
| - | - | - | - |
| Activate policy | `409` | The policy is already enforced. | Nothing to do. |
| Activate policy | `422` | The quorum has fewer than two approvers, or a direct activation was attempted. | Configure a quorum with at least two approvers in the dashboard. |
| Update, add rule, update rule, remove rule | `4xx` | The policy is not a draft. | Create a new draft. See [Change an enforced policy](https://www.bitnob.dev/docs/platform/policies/change-an-enforced-policy.md). |
| Create, add rule | `400` | `invalid_condition_field`, `invalid_operator`, `invalid_action_config`, or `unknown_action_config_field`. | Fix the rule. See [Rule reference](https://www.bitnob.dev/docs/platform/policies/rule-reference.md). |
| Create | `400` | `invalid_input`, for example "alert rules must specify at least one notify target". | Read `message`, and fix the rule. |
| Delete draft policy | `409` | The policy is not a draft. | Enforced and archived policies can't be deleted. A successful delete returns `204`. |
| Create draft policy, add rule | `400` | `Idempotency-Key` is missing. | Send one on every create. |
| Any idempotent write | `422` | `idempotency_key_conflict`: the `Idempotency-Key` was reused with a different body. | Use a new key for a new request. |
| Get quorum policy | `404` | No quorum is configured. | Configure one in the dashboard. |

All errors share the structure described in [Errors](https://www.bitnob.dev/docs/platform/making-requests.md#errors).

## Webhook events

Subscribe to these with [Create webhook](https://www.bitnob.dev/api-reference/platform/webhooks/create-webhook.md). [List supported event types](https://www.bitnob.dev/api-reference/platform/webhooks/list-supported-event-types.md) returns the current list.

| Event | Sent when |
| - | - |
| `policy.created` | A draft is created. |
| `policy.updated` | A draft's metadata changes. |
| `policy.rule.added` | A rule is added to a draft. |
| `policy.rule.updated` | A rule on a draft changes. |
| `policy.rule.deleted` | A rule is removed from a draft. |
| `policy.activated` | A draft becomes `enforced`, after quorum approves it. |
| `policy.archived` | An enforced policy moves to `archived`. |
| `policy.deleted` | A draft is deleted. |
| `policy.violation` | A `block` rule in the enforced policy blocked a transaction. |
| `policy.alert` | A transaction matched an `alert` rule. The rule's notify targets are informed. |

For approvals and time locks, follow the transaction itself: `transaction.signed` follows an approval or an expired time lock, and the transaction then moves through `transaction.broadcasting`, `transaction.confirmed`, and `transaction.completed`.

> [!TIP]
>
> Route `policy.activated`, `policy.archived`, and `policy.deleted` to your security channel. A policy change you didn't expect is worth investigating straight away.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.