Operate

Intents and retries

API Documentation

Every governed action your agent takes is an intent. When your agent moves money, creates a counterparty, asks a counterparty for its payment details, or requests a temporary limit increase (the console calls these temporary grants), we return an intent that records the action and its outcome. Reads, such as balances, transactions, and deposit addresses, do not return an intent.

An intent can pass through more than one status before it reaches a final one, so we recommend that your agent read the status every time instead of assuming the outcome.

Statuses and resolutions

Use status for control flow. Below are the five statuses that an intent may have, along with the matching resolution:

status resolution Meaning
completed completed The action has succeeded.
pending null The intent is waiting for a person to approve it.
processing null Catena has accepted the intent, and it is in progress.
blocked blocked, denied, or cancelled The intent cannot proceed. It may be blocked, denied or cancelled. This status is final; it alone does not prove that no money moved.
failed failed or expired The intent did not complete. This is final, but does not prove that no money moved; reconcile before another attempt.

resolution is the final outcome, and it is null while the intent is open. A block, denial and cancellation all have the status blocked. Read resolution and follow the recovery rules; a blocked resolution can include an unresolved payment attempt. We may add new resolution values, so pass through any value you don't recognize.

Only completed means success. If an intent is pending or processing, read it again until it reaches a final status:

Shell
catena intents get int_...

Intent fields

In addition to status and resolution, an intent carries the following fields that explain its result:

Field Contents
reasons The policy decision or the approval route. Your agent should summarize it for the user.
expiresAt The approval deadline for a pending intent.
metadata.dataUrl A link to the approval or the result in the console. Give it to the person who approves.
data The result, once one exists: the transaction for a send or transfer, or the new counterparty for a creation. It is null until then.

To list your agent's recent intents, you can filter by status, type, and start time (e.g., --status pending):

Shell
catena intents list --status pending --status processing
catena intents list --type send --start 2026-10-01T00:00:00Z

Exit codes

catena send and catena transfer exit 0 as soon as they submit the intent, even when the intent is blocked, pending, or later fails. This means a successful exit does not tell you whether money moved, so read .status and .reasons every time.

Cancel an intent

An agent can cancel its own intent while the intent is waiting for approval, after approval but before execution starts, or while it executes a bank payment that is prepared but not yet signed:

Shell
catena intents cancel int_...

The intent will end with resolution: "cancelled", and cancelling twice is safe. The API returns 409 (intent_not_cancellable) once the bank payment is signed, once its approval window has closed, or when the intent is executing in any other way. If another request is working on the payment at the same moment, the 409 comes with Retry-After: send the cancel again after that many seconds.

Retry safely

By default, each request waits up to 80 seconds. If a request times out, that means the client stopped waiting, but the server may still have acted on the request.

Reads are safe to run again. Intents are different, because an intent needs an idempotency key to be retried safely. The CLI and the SDK generate a new key for every call unless you pass one, so sending identical inputs twice will not mark the second request as a retry.

Example: retrying an ACH payment

Let's say Cora's Coffee's agent is paying Pete's Packaging $125.00 by ACH for invoice 4471. To be able to retry, the agent chooses a key (here, 7c4f2a8e-invoice-4471) and saves it before the first attempt:

Shell
catena send --rail cpr_... --amount 125.00 --method ach \
  --idempotency-key 7c4f2a8e-invoice-4471

If the request times out, find the original payment with catena intents list, then read catena intents get <id> for its status and resolution. If you cannot identify it, ask an admin before another attempt. Keep the saved key and unchanged inputs for a permitted retry while the original is still pending or processing. A blocked/blocked payment needs reconciliation even before reusing that key. Below is how we handle a repeated key, and when to use a new one:

Case What happens
Same key, same inputs A replay returns the original intent with replayed: true. A blocked/blocked key can instead create a fresh intent or return a 409 if its movement plan is retired. Reconcile the original payment before retrying on either key.
Same key, different inputs We return 409.
The policy changed A retry keeps the original source account, even if the policy changed.
A block was cleared Read status and resolution and ask an admin to confirm whether the original payment moved money before another attempt. A blocked/blocked outcome can retain an unresolved provider attempt; clearing a policy block alone does not establish that a new key is safe.
A new operation Use a new key for a new operation. For an earlier failed or expired payment, reconcile it first. If another attempt is confirmed appropriate, use a new key; the original key only replays the intent or conflicts with its retired plan.
Important

Completed intents

Don't pay a completed intent again to recover from an error.

Payment errors and retries

The following messages can come back from a payment, and each one calls for a different response:

Message What to do
"Already prepared" (409 wallet_send_intent_not_executing) Run intents get <id> if you have the ID. Otherwise ask an admin. Do not retry with a new key.
"Created but never submitted; no money moved." Fix the problem in the message, then use a new key.
"Could not be confirmed." Read intents get <id> until it is final, then read status and resolution. Stop on completed; accept denied. After cancelled, use a new key only if another attempt is appropriate. Ask an admin to reconcile the original payment for other blocked, failed, expired, or unknown outcomes before retrying on either key.

Using the SDK

In the SDK, submitIntent returns the intent's current state (it does not wait for execution). You can poll with getIntent(id), cancel with cancelIntent(id), and pass idempotencyKey yourself when a retry must refer to the same operation.

TypeScript
const intent = await client.submitIntent({
  action: { type: "send", counterpartyRailId, amount: "125.00", method: "ach" },
  idempotencyKey,
})
if (intent.status === "pending") {
  // Waiting for a person. intent.reasons says why.
}
Updated November 4, 2026 Applies to CLI 0.19.0 and @catena/sdk 0.11.0 View as Markdown