Errors

Request errors

A refused request answers a 4xx or 5xx with a JSON body:

{ "error": "wallet has no address yet" }

Field
`error`	Human-readable. Log it; do not branch on it — the wording can change.
`code`	Stable machine code, where one exists. Branch on this.
`retryable`	`true` when the same request may be sent again as-is.

Status	`code`	Meaning	What to do
`401`	—	Missing, unknown, revoked or expired API key.	Fix the key, or mint a new one.
`403`	`ip_not_allowed`	The call came from an address outside the key’s IP allowlist.	Call from an allowed address.
`403`	`scope_missing`	The key lacks the scope this endpoint needs (Authentication).	Use a key with that scope.
`403`	`vault_limited`	The key is limited to vaults: the wallet is outside them, or the endpoint drives or lists workflows, manages webhook endpoints, reads webhook deliveries, reads or changes the policy document, or asks for or reads a report. Nothing was created or reserved.	Use a key that reaches the wallet, or one without vault limits.
`404`	—	No such resource in your organization, or outside the key’s vaults. A list’s `wallet` filter that names no such wallet, and a `vault` of `GET /balances` that is not yours, answer the same; so does `GET /policy` before a policy document is published, and `POST /policy/publish` of a version with no draft.	Check the id and `network`.
`409`	`idempotency_conflict`	The idempotency key was used with a different body (`/transactions`), or with other inputs or another `network` (`/events/{name}`).	Use a new key, or resend the original request.
`409`	`delivery_not_failed`	A webhook delivery retry named one that is pending (already on its way) or delivered. Nothing changed.	Nothing to do: only a failed delivery is sent again.
`409`	`endpoint_disabled`	A webhook delivery retry named one whose endpoint is paused or disabled, or a test was sent to such an endpoint. Nothing changed.	Resume the endpoint (`PATCH /webhook_endpoints/{id}` with `state: active`, or in the console), then retry.
`409`	`endpoint_exists`	`POST /webhook_endpoints`, or a `PATCH` of its `url`, named a URL your organization already has an endpoint for. Nothing changed.	Read that endpoint with `GET /webhook_endpoints` and change it with `PATCH`.
`409`	`not_a_draft`	`POST /policy/publish` named a version signed already (pending, published or rejected), with another signature. Nothing changed.	Draft a new version with `POST /policy/drafts`. See Address book.
`409`	`policy_key_missing`	`POST /policy/publish`: no policy key is registered for your organization, so the signature cannot be checked. Nothing changed.	Bring your policy engine up: it registers its policy key when it joins.
`409`	`not_cancellable`	`POST /transactions/{id}/cancel` came too late: the transaction is past approval (on its way to your signer, signed, on chain or ended — the `error` says which), its quorum already decided, or a workflow’s batch carries it. Or it was not sent through the API: a workflow’s transaction stops with its run. Or `POST /runs/{id}/cancel` did: a transaction of the run has reached `authorized`, the run has ended, or another run started it. Nothing changed.	Follow it to its end with `GET /transactions/{id}` or `GET /runs/{id}`.
`409`	`not_cancellable`	`POST /runs/{id}/cancel` while the run is executing a step. Nothing changed.	Send the same call again in a moment.
`409`	`not_speedable`	`POST /transactions/{id}/speedup` of a transaction that cannot be sped up: not an EVM transfer from a standard account, or sponsored; not signed yet, or ended; waiting less than 5 minutes; a speedup of it still waiting for your signer; its nonce already mined; or the wallet cannot cover the higher network fee. Nothing changed.	Read `error`. Too early: ask again after 5 minutes. Mined: it settles on its own. Funds: top the wallet up.
`409`	`report_not_ready`	`GET /reports/{id}/file` before the report is ready: it is `queued` or `running`.	Follow it with `GET /reports/{id}`, then fetch the file once it is `ready`.
`409`	`report_failed`	`GET /reports/{id}/file` of a report that failed: it has no file.	Ask for a new one with `POST /reports`.
`409`	`not_retirable`	`POST /wallets/{reference}/retire` of a wallet with no address: still `creating`, or `failed`. Nothing changed.	Wait for `wallet.active`, then retire it; a `failed` wallet needs nothing.
`422`	`invalid_cursor`	A list’s `cursor` is not one this API issued. Nothing was read.	Start again from the first page, without `cursor`. See Lists and pagination.
`422`	—	A list’s filter value it does not know (a `status` that does not exist), a filter sent as a list or an object instead of one string, a time that is not ISO 8601, or a `limit` out of range; a webhook retry of a period without `from`. Nothing was read or changed.	Fix the parameter.
`422`	`invalid_signature`	`POST /policy/publish`: `signature` is not a 64-byte Ed25519 signature in hex or standard base64. Nothing changed.	Send the signature your policy key made.
`422`	`signature_mismatch`	`POST /policy/publish`: the signature does not verify over the draft’s bytes with your policy key. Other bytes were signed, or another key signed. Nothing changed.	Sign `document` exactly as `POST /policy/drafts` answered it, with your policy key (key B).
`422`	`nothing_changed`	`POST /policy/drafts` with the rules in force. The draft was not replaced.	Nothing to do.
`422`	`invalid_request_signature`	`X-Citadel-Request-Signature` is not base64 of a 64-byte Ed25519 signature. Nothing was created or reserved.	Send the signature bytes in standard, padded base64.
`422`	`network_required`	The request names no `network`. There is no default network. Nothing was created or reserved.	Send `network`. See Networks.
`422`	`network_not_served`	Your installation does not serve this `network`, or the value is not a network. Nothing was created or reserved.	Send a network your installation serves.
`422`	`network_mismatch`	The wallet named by its id lives on another network than the request names. Nothing was created or reserved.	Send the wallet’s own `network`, or name a wallet on that network.
`422`	—	Understood and refused: unknown wallet, unsupported chain, a new wallet without `end_user_ref`, a wallet or webhook endpoint change that names a field it cannot change, a webhook URL that is not an `https://` URL with a host, a webhook endpoint field sent in the query string instead of the body, an unknown event type, an `overlap_seconds` out of range, bad amount, no workflow on this event, invalid inputs. A policy draft your engine could not read (a field the document does not have, an address its chain cannot parse, an amount that is not an integer string), a policy publish whose `version` is not an integer. A wallet batch refused by one of its items names the item’s index (`wallets[3]: …`). A report asked for with an unknown `type` or `format`, or with a wallet or `window_days` its type does not take. Nothing was created, changed or reserved.	Fix the request.
`503`	`rpc_unavailable`	A chain node stayed down through retries. Nothing was created or reserved.	Wait `Retry-After` seconds, resend with the same idempotency key.

Transaction failures

202 means accepted, not done. A transaction that later ends without moving its money has status: failed (or expired) and a failure block — on GET /transactions/{id}, in its row of GET /transactions, and in the operation.failed webhook:

{
  "operation_id": "0199a3c4-8a00-7c22-8d3e-4f5a6b7c8d9e",
  "status": "failed",
  "failure": {
    "stage": "engine",
    "reason": "policy_refused",
    "retryable": false,
    "message": "The policy engine refused the payout. Nothing was signed.",
    "detail": "daily limit exceeded for end_user_ref user-4211"
  }
}

reason comes from a closed set:

`reason`	`retryable`
`window_expired`	✅	The validity window closed before it landed. Nothing moved.
`rpc_unavailable`	✅	A node could not be reached while building. Nothing was signed.
`build_failed`	—	The transaction could not be built from this request.
`sequence_refused`	—	The fee payer’s next nonce was refused (a reset or lagging chain node, or a stuck fee-payer transaction). Nothing was sent; it fails the same way until an operator settles the fee payer’s nonces.
`policy_refused`	—	Your policy engine refused.
`signing_failed`	—	Your signer refused.
`rejected_by_chain`	—	Every node refused the signed transaction. Nothing moved.
`reverted`	—	It landed and failed. The amount did not move; the network fee was spent.
`approval_rejected`	—	An approver rejected it.
`approval_expired`	—	Not approved in time.
`approval_stale`	—	It changed after it was sent for approval.
`cancelled`	—	You cancelled it (`POST /transactions/{id}/cancel`) before it was signed. Nothing was signed or moved.

retryable: true means it is safe to submit again with a new idempotency key. Anything else would fail the same way: look before resubmitting. cancelled is not retryable on purpose: a retry loop that resubmits every retryable failure would undo your cancel. On TON, window_expired is declared only once the chain index provably serves every transaction of the sending wallet through the window. Should a transaction still land after window_expired, the chain wins: the same operation gets operation.confirmed with corrected: { from: "expired", failure, at }, and GET /transactions/{id} carries the same corrected from then on.

Workflow failures

A run that stops has status: failed and a free-text failure_reason on GET /runs/{id}, in its row of GET /runs, and in run.failed. A run you cancelled with POST /runs/{id}/cancel has status: cancelled, failure_reason: cancelled through the API, and run.cancelled.

Get started

Merchant stack

Conventions

Notifications

Policy

Request errors

Transaction failures

Workflow failures

​Request errors

​Transaction failures

​Workflow failures

Request errors

Transaction failures

Workflow failures