recovery.operation_failed

A recovery failed before changing anything; the allowance it spent is given back.

When this fires

The recovery was opened in the ledger and then could not be carried out: the connector refused the new bot's credentials, the replacement chat could not be bound, the new account could not be linked. Nothing changed, so the operation is marked failed and its use of the rolling allowance is given back. The creator sees the refusal on the page that ran it; this event tells your systems.

Required ability

project-recovery:view — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "recovery.operation_failed",
  "created_at": "2026-09-12T09:41:07Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "operation_id": "c2e8f1a9-6d47-4b3e-9f05-1a8d7c2e4b60",
    "kind": "bot",
    "connector": "telegram",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "automatic": false,
    "on_demand": false,
    "started_at": "2026-09-12T09:41:05Z",
    "failure_reason": "The platform refused the token."
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `recovery.operation_failed` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string UUID \| null	Project this event belongs to; null for an account recovery.
`data.operation_id`	string UUID	The failed operation.
`data.kind`	string	`account`, `bot` or `resources`.
`data.connector`	string \| null	The connector the recovery acted on.
`data.project_id`	string UUID \| null	The project, or null for an account recovery.
`data.automatic`	boolean	True when the platform ran it without the creator.
`data.on_demand`	boolean	True for a Swap & Grant of a healthy resource.
`data.started_at`	ISO 8601 timestamp	When it began.
`data.failure_reason`	string \| null	What went wrong, as the ledger recorded it.

Caveats

A swap that fails while a channel recovery is already absorbing swaps leaves that recovery standing: failing it would erase a swap that did happen. Only a recovery that failed on its first swap fires this.

recovery.operation_started — how it began.
Recovery events overview — back to family overview.