Intents and retries
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:
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):
catena intents list --status pending --status processing
catena intents list --type send --start 2026-10-01T00:00:00ZExit 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:
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:
catena send --rail cpr_... --amount 125.00 --method ach \
--idempotency-key 7c4f2a8e-invoice-4471If 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. |
ImportantCompleted intents
Don't pay a
completedintent 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.
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.
}