Status & Errors

Every owner intent and every agent action gets a correlation_id. Check its result with GET /v1/status, and read the error document when a call fails.

At a glance

Poll until final: SUCCESS, REFUNDED or FAILED. wait_ms (up to 30 s) holds the answer until something changes.
Retry a write with the same Idempotency-Key and the same body. A new key is new work.
Outcome not yet proven (UNCERTAIN)? Keep polling the same correlation_id. Never send the action again under a new key.
Errors: branch on errors[0].code, never on the text. layer says whose rule refused. Unknown codes fall back to the HTTP status.

Check a status

GET /v1/status reads the status of any correlation_id (intent_… for owner intents, op_… for executions and deposits). It needs your partner API key.

Query parameter	Description
`correlation_id`	Required. The id a generate-intent or execution call returned.
`wait_ms`	Optional, 0 to 30000, default 0. Waits up to this long for the status to settle.
`refresh`	Optional, `true` or `false`. Observes the provider again after a review. See NEEDS_REVIEW.

curl "$NEAR_INTENTS_AGENT_API_URL/v1/status?correlation_id=$CORRELATION_ID&wait_ms=30000" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

const status = await api.getStatus(correlationId, { waitMs: 30_000 });
console.log(status.type, status.status, status.failure_code);

wait_ms returns as soon as the status is final, needs a signature (PENDING_SIGNATURE) or needs review (NEEDS_REVIEW). Otherwise it returns the current status when the wait ends. A non-final answer is normal: call again with the same correlation_id. Each check also reconciles the status with chain and provider state, so you never need a separate refresh to keep it current. At most 10 wait_ms waits run at the same time per API key. Further ones answer at once, as plain reads. Poll in a loop:

type Status = Awaited<ReturnType<typeof api.getStatus>>;

const final = new Set(["SUCCESS", "REFUNDED", "FAILED"]);

async function waitForFinal(correlationId: string): Promise<Status> {
  for (;;) {
    const status = await api.getStatus(correlationId, { waitMs: 30_000 });
    if (final.has(status.status)) return status;
    if (status.status === "NEEDS_REVIEW") return status;
    if (status.status === "PENDING_SIGNATURE") return status;
  }
}

Status values

Status	Meaning	Final
`PENDING_SIGNATURE`	An owner intent waits for the owner’s signature, before it expires	No
`QUEUED`	Waiting for the agent’s timelock to pass	No
`PENDING_APPROVAL`	Waiting for the owner to approve	No
`PENDING_DEPOSIT`	Waiting for the payer’s funds at a deposit address. Only deposits report it.	No
`PROCESSING`	In progress. A withdrawal’s or swap’s bridge leg waiting on 1Click reads `PROCESSING`, and `details.provider_status` keeps the provider’s own state. So does a provider `success` whose settlement it still reports pending, until the settlement deadline.	No
`UNCERTAIN`	The outcome is not yet proven. Keep polling the same `correlation_id`. See UNCERTAIN.	No
`NEEDS_REVIEW`	Automatic settlement stopped. See NEEDS_REVIEW.	No
`SUCCESS`	Done, with evidence	Yes
`REFUNDED`	The route refunded the input	Yes
`FAILED`	Provably never executed, or failed with a recorded reason. `failure_code` says why.	Yes

SUCCESS appears only with proof: an intent hash on NEAR Intents, the transaction on the destination chain for a withdrawal to another chain, or the settled transaction of a native NEAR transfer or call. A sent transaction alone does not count as success. Owner intents move through PENDING_SIGNATURE, PROCESSING, SUCCESS and FAILED.

Status fields

Field	Description
`correlation_id`	The id you are tracking
`agent_id`	The agent the intent or action belongs to
`type`	`agent_create`, `policy_update`, `agent_freeze`, `agent_unfreeze`, `grant_issue`, `grant_revoke`, `execution_cancel`, `agent_archive`, `agent_restore`, `agent_delete`, `approval_vote`, `swap`, `withdraw`, `transfer`, `shield`, `unshield`, `deposit` or `native`. `details` depends on it.
`status`	One of the values above
`failure_code`	A snake_case reason when `status` is `FAILED`, `REFUNDED`, `UNCERTAIN` or `NEEDS_REVIEW`. For a refusal it is the error code that refused the action. Otherwise `null`.
`created_at`, `updated_at`	ISO 8601 times
`dispatch_committed_at`	When the API committed to sending the action to the agent wallet. `null` before that and for owner intents. After it, revoking a key or a grant cannot stop the action. See Executions.
`grant`	`{ id, label }` of the grant that allowed the action. `null` for owner intents and for deposit addresses.
`details`	Type-specific evidence

Execution details (swap, withdraw, transfer, shield, unshield, deposit, agent_delete) can hold these fields. Only the ones that apply are present.

Field	Description
`action`	The action name
`request`	The request as admitted, in the request body’s field names. Only the fields the request had are present: `origin_asset`, `destination_asset`, `asset`, `amount`, `min_amount_out`, `chain`, `recipient`, `memo` and `confidential` (the balance it spends from, or for a deposit credits). It lets a client show a transfer’s recipient and reserve per asset. Executions admitted before it was recorded have none.
`near_account_id`	The agent’s NEAR Intents account
`provider_status`	The provider’s own status for the request
`provider_request_id`	The provider’s reference. `null` until the action is sent.
`intent_hash`, `tx_hash`, `destination_tx_hash`	On-chain evidence
`amount_out`	The amount delivered, as an atomic string. Present only when `status` is `SUCCESS`, or `REFUNDED` after a partial fill. Before that the figure is `expected_amount_out`. Wait for `SUCCESS` before you treat an amount as final.
`expected_amount_out`, `min_amount_out`	`expected_amount_out` is what the quote or provider reports before the action completes; a deposit keeps its quoted figure here after it settles. Both are atomic strings.
`execute_after`, `delay_ms`	A queued action’s release time and the timelock that applied
`approval_id`	The approval waiting on the owner, when `status` is `PENDING_APPROVAL`
`deposit_address`, `memo`, `min_amount`, `expires_at`, `refund_to`, `refund_tx_hash`	Deposits. An unpaid deposit ends `FAILED` with `deposit_expired` one day after `expires_at`. See Funding an Agent. `min_amount` also appears on any execution refused with `amount_too_low` when the provider stated the route minimum: the smallest amount, in atomic units of the asset sent.
`failure_reason`	A short reason the route gave for a refund or failure
`policy_record`	`agent_delete` only. The cleanup of the agent’s stored policy record: `{ status, transaction_hash, refund_to, storage_deposit_yocto, reason? }`. `status` is `pending`, `deleted`, `absent`, `kept` or `unknown`. After the deletion completes, the API relays the owner-signed `delete_wallet_policy`, which refunds the policy’s storage deposit to `refund_to`, the sponsor that paid it. This cleanup is best effort and the deletion stands either way. `kept` names its `reason`: the record is left in place and still refunds the same account whenever its owner deletes it. `unknown` means the transaction was broadcast without an observed outcome.

Owner intent details: agent_create, policy_update, agent_freeze and agent_unfreeze carry revision, policy_hash and transaction_hash (agent_create also agent_id). grant_issue carries grant, grant_revoke carries grant_id, committed_correlation_ids and committed_truncated, execution_cancel carries cancelled_correlation_id, agent_archive and agent_restore carry archived, and approval_vote carries approval_id and verdict. native details say what was asked of the agent’s own key: method, chain, account_id, target, amount, method_name, primary_type, domain, message_json, request_sha256, signature, tx_hash, provider_request_id, provider_status and failure_reason. See Native Accounts.

List an agent’s history

GET /v1/agents/{agent_id}/history lists everything an agent has done, newest first, one status object per entry. Every deposit lookup issues a new address, so history leaves out deposit addresses nothing was paid into (still open, expired, or closed by a deletion). Add include_unpaid=true to list them too. Each one stays readable by its correlation_id through GET /v1/status, and an address paid in part is always listed.

curl "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/history?limit=25" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

let cursor: string | undefined;
do {
  const page = await api.getHistory(agentId, { limit: 50, cursor });
  for (const entry of page.data) console.log(entry.created_at, entry.type, entry.status);
  cursor = page.next_cursor ?? undefined;
} while (cursor);

Parameter	Description
`limit`	1 to 100, default 25
`cursor`	The `next_cursor` of the previous page. An invalid one returns `invalid_cursor` (400).

The response is { "data": [...], "next_cursor": "..." }. next_cursor is null on the last page. History entries are shown as stored. They are not reconciled with chain and provider state, so an entry can lag behind the real outcome. Track one item with GET /v1/status instead.

Idempotency

An Idempotency-Key is a name you give one write, so a retry cannot run it twice. Every execution, deposit and /recover call needs one, and a missing key returns idempotency_key_required (400). generate-intent accepts an optional one. A key is 8 to 128 characters of A-Za-z0-9._:-. A UUID works well.

Retry with the same key and the same body. You get the first result back, with the same correlation_id.
The same key with a different body fails with idempotency_conflict (409). Reuse the original body, or use a new key for new work.
Keys are scoped to the grant. The same key under two grants is two separate actions.
Recorded refusals are remembered. When the API refused an action it had already admitted, for example with wallet_busy, the same key returns the same FAILED result. Such an error never carries meta.retryable. After the cause is gone, send the work again under a new key.
Budget and limit refusals are not recorded. A new execution that would run now and exceeds the USD budget or a per-asset limit (spend_budget_exceeded, spend_price_unavailable, policy_limit_exceeded, policy_action_limit_exceeded, policy_usage_unavailable) is a plain refusal: no operation, no FAILED status, no charge. The same key is judged again each time and refuses again while the cause lasts. A FAILED row is recorded only when a request loses a concurrent race at the dispatch commitment, or a timelocked request is released over budget or a limit; its key then replays that outcome.
A new key is new work. Never use one to retry an action that is UNCERTAIN, PROCESSING or already dispatched.

The SDK creates a key when you omit one, for generate-intent as well, and returns it as idempotencyKey on the result. It never retries a write by itself. A transport failure surfaces as an error that carries the key, so you can resend with it. For crash safety, create the key with createIdempotencyKey(), save it, then send the request.

When the result is unknown

Never send an UNCERTAIN action again with a new Idempotency-Key. The first attempt may have worked, and a new key would run the action a second time.

UNCERTAIN

UNCERTAIN means the outcome is not yet proven: the API sent, or may have sent, the action and has not yet seen the result. Most of these settle on their own into SUCCESS, FAILED or REFUNDED. What to do:

A refusal never hides an UNCERTAIN action. When a request may have reached the agent wallet, the response is 202 with status UNCERTAIN and the action’s correlation_id, even if the provider’s answer looked like a refusal. If the API itself fails, you get a server error with meta.retryable: send the same request again with the same key, which returns the action without sending it twice.
Keep polling the same correlation_id. Every check reconciles the status with the provider.
failure_code: settlement_overdue means the provider still reports the request in progress after the settlement deadline. A provider success whose settlement is still pending reads PROCESSING until then. Keep polling: observation continues, and a late settlement still completes the action.
Lost the response to your request? Retry with the same key, or read the status of the correlation_id you saved. Do not start anything new until you know the result.
Stuck before it was sent? POST /v1/agents/{agent_id}/recover dispatches an UNCERTAIN execution once, but only when the API can prove it never reached the agent wallet: it has no provider reference and no dispatch commitment. It cannot force through an action whose result is unknown.

NEEDS_REVIEW

NEEDS_REVIEW means the provider reported a state that automatic settlement cannot resolve. failure_code is provider_review_required, and details.provider_status and details.failure_reason hold what the provider said. details.reason says why settlement stopped. A swap the provider reports as successful but below its min_amount_out reads NEEDS_REVIEW with amount_out_below_minimum, never SUCCESS. A native NEAR transfer or call whose provider answer was lost reads NEEDS_REVIEW with native_request_unconfirmed once the API stops resending it, 10 minutes after dispatch. See Native Accounts.

Stop polling. Routine status reads do not observe the provider again while the status is NEEDS_REVIEW.
Never retry it or send it again. Funds may have moved.
After the review is resolved, read the status with refresh=true. This is the one explicit observation of the original request, and it can move the status to a final value.

const status = await api.getStatus(correlationId, { refresh: true });

refresh=true can also repair the USD budget charge of a historical failed execution when the provider proves no funds moved.

Budget charges and failures

An execution’s USD charge is decided at the dispatch commitment. The API releases the charge only when it can prove the action never spent: the failure carries details.never_executed or never_submitted. Those flags come from the provider itself; a failure reason such as a balance that ran short (failure_code: insufficient_balance) is not proof, so that failure keeps its charges. An UNCERTAIN or NEEDS_REVIEW action keeps its charge until the result is known. See USD budget.

Owner intents

Owner intents (create, policy, freeze, grants) finish on their own after the signature is submitted. Keep checking the status. An unsigned intent expires, and a new one needs a new generate call.

Error format

Every error is a JSON:API document. Branch on errors[0].code, never on title or detail.

{
  "errors": [
    {
      "status": "409",
      "code": "wallet_busy",
      "layer": "provider",
      "title": "Wallet busy",
      "detail": "The agent's wallet is running another money operation. Once it finishes, send this work again under a new Idempotency-Key; this one replays the refusal."
    }
  ],
  "meta": { "request_id": "6a1f2c0e-3b7d-4c2a-9e15-8f0d4b6a2c71" }
}

Field	Description
`errors[].status`	The HTTP status, as a string
`errors[].code`	A stable snake_case code. The table below lists them.
`errors[].layer`	Whose rule refused: one of the eight layers
`errors[].title`	The code in words, for people
`errors[].detail`	What to do next, when there is something to say
`errors[].meta.retryable`	Present and `true` when the identical request, with the same `Idempotency-Key`, can succeed after `Retry-After`
`errors[].meta.available_at`	An ISO 8601 time when the limit or cooldown frees up. Present with rate limits, quotas and cooldowns.
`errors[].meta.available_amount`	On `insufficient_balance` only, when known: what the balance the request spends from can still spend, in atomic units. It is the `available_raw` of the balances read, which leaves out queued work.
`errors[].meta.min_amount`	On `amount_too_low` only, when the provider states the route minimum as a whole number: that minimum, in atomic units of the asset sent. Quote at least that. When absent, the provider gave no number. A refusal recorded on an operation keeps it as `details.min_amount`.
`errors[].source.pointer`	On validation errors, the field at fault
`meta.request_id`	Quote it when you ask for support. It is also the `X-Request-Id` response header.

A response with meta.retryable: true also carries a Retry-After header with the wait in whole seconds. So does any response with meta.available_at, even a recorded refusal without meta.retryable: there the header says when new work can succeed, not that the same key can. Validation errors (validation_failed, 400) return one entry per invalid field, up to 20. source.pointer is a JSON pointer: /amount for a body field, /query/wait_ms, /path/agent_id or /header/… for the others. Unknown codes. The list grows over time. Handle a code you do not know by its layer and its HTTP status: 4xx means fix the request, 429 and 503 mean retry only if meta.retryable is set, as described below, and 5xx otherwise means try again later or ask for support with the request_id.

import { AgentApiError } from "@near-intents-agent-api/sdk";

try {
  await api.forGrant(grantToken).swap(agentId, request);
} catch (error) {
  if (!(error instanceof AgentApiError)) throw error;
  console.error(error.status, error.code, error.retryable, error.availableAt, error.requestId);
}

Decide from code, layer, meta.retryable and the status, never from detail:

meta.retryable: true: send the identical request again, with the same Idempotency-Key, after Retry-After. Server errors (internal_error, database_busy, transaction_unconfirmed) carry it because the request may have taken effect; only the same key can safely find out.
No meta.retryable: sending the same request again will not help now. It does not prove that an earlier attempt sent nothing.
A new key only after a proven refusal: a code whose “What to do” column says nothing was sent, such as policy_action_denied or a wallet_busy recorded as the action’s outcome (its key replays the refusal). Send the new work only once the cause is gone. A FAILED or REFUNDED status is not such proof, since a partial failure is also FAILED: check its details and the balances before you decide to send new work, and never retry it automatically.
Earlier work under the key: after a server error or a lost response, on intent_generation_recovery_required, operation_not_recoverable or operation_not_pending, or on any error from /recover, the first outcome may still be unknown. Keep the original key and correlation_id and read the status.
No response at all (timeout or network error): the result is unknown. Send the same request with the same key.
202 with UNCERTAIN: not an error. Poll that correlation_id and never send the work under a new key.

Error layers

Every error carries a layer that names whose rule refused. Only a change to that layer lifts the refusal. Branch on code for the exact refusal and read layer to know who acts next.

Layer	Whose rule	What to do
`request`	The request itself: shape, ids, assets, addresses, amount minimums, idempotency, resource state	Fix the request. Repeating it unchanged will not help.
`auth`	Who is asking: API key, owner signature, nonce, intent	Fix the credential, or generate and sign a new intent.
`grant`	The grant that admits the agent’s calls	Send a live grant’s token, or issue a grant.
`policy`	The account policy and the account’s state: actions, assets, destinations, schedule, limits, freeze, archive	Ask the owner to change the policy with `policy_update`, or wait until the schedule or window allows it.
`budget`	The shared USD budget and its price	Ask the owner to raise a cap, or wait until `resets_at`. For `spend_price_unavailable`, wait for a usable price.
`balance`	The agent’s balance	Fund the agent, or send a smaller amount.
`provider`	The custody provider, 1Click and routing	With `meta.retryable`, send the same request with the same key after `Retry-After`. Otherwise change the pair or amount, or wait: nothing was sent.
`api`	This service: internal errors, database, sponsor, RPC, quotas, rate limits	With `meta.retryable`, the same request with the same key after `Retry-After`. Otherwise try later, or contact support with the `request_id`.

meta.retryable keeps its meaning in every layer: true says the same Idempotency-Key can succeed, and its absence proves nothing about an earlier attempt.

Error codes

The Layer column is the layer of the error. The Retryable column says whether the response carries meta.retryable: true. “At available_at” means it does, with a time. A refusal recorded as an action’s outcome never carries it, whatever the column says.

Request and authentication

Code	Layer	HTTP	Retryable	What to do
`validation_failed`	`request`	400	No	A field is invalid. Read `source.pointer` and `detail` of each entry. Among others: an `amount` of zero on any action that moves funds, a swap whose `origin_asset` and `destination_asset` are the same, and a `native/evm/sign-transaction` or `native/solana/sign-transaction` payload that is not one transaction of the kind the route signs.
`invalid_json`	`request`	400	No	The body is not valid JSON
`invalid_api_key`	`auth`	401	No	Send a live API key in the `X-API-Key` header
`not_found`	`request`	404	No	No such endpoint
`internal_error`	`api`	500	Yes	The API hit an unexpected error, possibly after the request took effect. Send the same request with the same `Idempotency-Key`, never a new one. If it keeps failing, contact support with the `request_id`.
`invalid_cursor`	`request`	400	No	Use a `next_cursor` exactly as returned
`operation_not_found`	`request`	404	No	No intent, execution or operation with this id for this API key and agent. Pass the `correlation_id` exactly as it was returned.
`intent_not_found`	`request`	404	No	No such intent. Check the `correlation_id`.
`tenant_not_found`	`auth`	404	No	The partner account does not exist for this key

Idempotency

Code	Layer	HTTP	Retryable	What to do
`idempotency_key_required`	`request`	400	No	Send an `Idempotency-Key` header that is stable for this logical request
`idempotency_conflict`	`request`	409	No	The key was used with a different body. On `/recover` it also fires when the `Idempotency-Key` differs from the original execution’s key. Reuse the original body and key, or use a new key for new work.
`operation_retired`	`api`	409	No	The operation behind this key was retired and can no longer be replayed. Use a new key.
`database_busy`	`api`	503	Yes	The API is busy, and the request may have taken effect. Send it again with the same `Idempotency-Key`, never a new one.

Rate limits and capacity

Code	Layer	HTTP	Retryable	What to do
`rate_limited`	`api`	429	Yes	Too many requests for your key or partner account. Wait for `Retry-After`.
`agent_creation_quota_exceeded`	`api`	429	At `available_at`	The daily agent limit. See Network & Quotas.
`deposit_quota_exceeded`	`api`	429	At `available_at`	The agent’s daily deposit address limit
`policy_change_throttled`	`policy`	429	At `available_at`	A policy change was made within 10 minutes. Submit again at `available_at`.
`agent_unfreeze_throttled`	`policy`	429	At `available_at`	An unfreeze was made within 10 minutes. Submit again at `available_at`.
`provider_rate_limited`	`provider`	429	Yes, except for an execution	The wallet provider throttled the request. Nothing was sent. Wait for `Retry-After`; an execution’s refusal is recorded, so send it again under a new key after a short wait.
`sponsor_busy`	`api`	503	Yes	All sponsor keys are busy. Retry shortly.
`sponsor_balance_insufficient`	`api`	503	Yes	The service cannot pay network fees right now. Send the same request later.
`wallet_sponsor_disabled`	`api`	503	No	This deployment does not sponsor owner transactions. Contact support.

Agents and lifecycle

Code	Layer	HTTP	Retryable	What to do
`agent_not_found`	`request`	404	No	No such agent for your partner account
`agent_not_bound`	`request`	409	No	The agent is still onboarding. Wait for its `agent_create` intent to reach `SUCCESS`.
`agent_archived`	`policy`	409	No	The agent is archived. Restore it first with `agent_restore`.
`agent_not_archived`	`request`	409	No	Only an archived agent can be restored
`agent_deleted`	`policy`	409	No	The agent is deleted
`agent_deletion_pending`	`policy`	409	No	A delete is in progress. Follow its `correlation_id`.
`wallet_frozen`	`policy`	409	No	The owner froze this agent. Only an `agent_unfreeze` intent resumes executions.
`wallet_already_frozen`	`request`	409	No	The agent is already frozen. Nothing to do.
`wallet_already_unfrozen`	`request`	409	No	The agent is not frozen. Nothing to do.
`onboarding_not_found`	`request`	404	No	No onboarding for this agent
`onboarding_not_pending`	`request`	409	No	Onboarding is no longer pending. Read its status.
`onboarding_expired`	`request`	409	No	The signing window closed. Generate a new `agent_create` intent.
`onboarding_conflict`	`request`	409	No	The onboarding conflicts with the agent’s current state. Read its status. If it persists, contact support with the `request_id`.

Grants

Code	Layer	HTTP	Retryable	What to do
`agent_grant_required`	`grant`	403	No	Send `X-Grant-Token` with the token of a live grant on this agent. Issue one with a `grant_issue` intent.
`grant_not_found`	`request`	404	No	No such grant on this agent
`grant_limit_reached`	`grant`	409	No	The agent holds the maximum of live grants (50). Revoke one it no longer needs.
`grant_credential_reused`	`grant`	409	No	The token already backs another grant. Create a new token for every grant.
`grant_expiry_invalid`	`grant`	409	No	`expires_at` is in the past or more than 365 days away
`grant_wallet_mismatch`	`grant`	409	No	The grant belongs to a different agent wallet
`grant_action_unsupported`	`request`	403	No	This action cannot run under a grant

Refused by the account policy

The API checks these before anything is sent. Nothing was spent. See Policies & Limits. The action, destination, asset, schedule, USD budget and per-asset limit codes below refuse the live request. A swap quote or withdrawal preview (dry: true) is not refused by them: it returns 200 and lists each rule the live request would fail in warnings, under the same code: policy_action_denied, policy_destination_denied, policy_asset_denied, policy_schedule_denied (with available_at), spend_budget_exceeded, spend_price_unavailable, policy_limit_exceeded, policy_action_limit_exceeded or policy_usage_unavailable. insufficient_balance (with available_amount) is a warning too. unsupported_token and invalid_address refuse the quote itself with 400, before any provider call, and use no preview attempt. A withdrawal preview uses one of the 20 daily preview attempts every time it reaches the provider, rule warning or not. A provider refusal, an outage and an uncertain attempt stay counted; only an answer the provider gives before running anything (its rate limiter’s 429, wallet_busy, provider_limit_reached) gives the attempt back. A new execution that runs now and exceeds the USD budget or a per-asset limit is a plain refusal: no operation, no FAILED status, no charge, and the same key refuses again while the cause lasts. A FAILED row is recorded only when a request loses a concurrent race at the dispatch commitment, or a timelocked request is released over budget or a limit; its key then replays that outcome. An archived, deleted or frozen account gets no quote: a swap quote and a withdrawal preview are refused with agent_archived, agent_deleted or wallet_frozen, reach no provider and use no attempt. See Account rules in a quote.

Code	Layer	HTTP	Retryable	What to do
`policy_action_denied`	`policy`	403	No	The policy does not allow this action. The owner enables it with `policy_update`, and every grant can use it at once.
`policy_destination_denied`	`policy`	403	No	The policy’s destination rule does not allow this address. The owner adds it with `policy_update`.
`policy_schedule_denied`	`policy`	403	At `available_at`	The schedule does not allow money actions when this request would run. Nothing was recorded: submit the same request again at `meta.available_at`, or ask the owner to change `schedule`.
`spend_budget_exceeded`	`budget`	403	No	The shared USD budget has too little left. Nothing was recorded or charged. Read `usage.budget` from the policy, or `spend.budget` from a dry run. Each cap’s `resets_at` is when its current period ends and the whole cap is available again. The owner raises a cap with `policy_update`, or you send the request again after `resets_at`.
`policy_limit_exceeded`	`policy`	403	No	The amount would pass the owner’s hourly, daily or monthly limit for this asset. Shield and unshield count too. Nothing was recorded or charged. The owner raises the limit with `policy_update`, or you send the request again once earlier actions leave the window. See Per-asset limits.
`policy_action_limit_exceeded`	`policy`	403	No	The agent used its `max_actions_per_hour`. Nothing was recorded or charged. Send the request again once earlier actions leave the hour, or the owner raises the cap.
`policy_usage_unavailable`	`policy`	409	No	The agent has earlier actions the API has no per-asset count for, and a limit applies to this asset. Nothing was recorded or sent. It clears once those actions leave the window. Ask the API operator to reconcile them sooner.
`spend_price_unavailable`	`budget`	503	No	The asset has no usable USD price, so the budget cannot count it. Nothing was recorded or charged. Send the request again once `GET /v1/tokens` shows a price.
`policy_not_ready`	`policy`	409	No	The latest policy revision is not in force yet. Wait for the pending policy intent to settle.
`native_method_denied`	`policy`	403	No	The policy’s `native` block does not switch this method on, or does not list this contract or EIP-712 domain, or the matching domain entry’s `primary_types` does not list the request’s `primaryType`. The owner enables it with `policy_update`. See Native Accounts.
`signing_policy_denied`	`policy`	403	No	The recipient is not in the policy’s `native.near.sign_message`. The owner adds it with `policy_update`.

Refused by the wallet provider

The wallet provider checks the rest of the policy, and the request itself. These answer HTTP 409 unless the row says otherwise. Each one is decided before anything is sent, so nothing moved. Fix the cause, then send the work under a new Idempotency-Key. A refusal recorded as the action’s outcome replays under its own key and never carries meta.retryable. One returned before the action was admitted does carry it, and then the same key works after Retry-After.

Code	Layer	HTTP	Retryable	What to do
`policy_denied`	`policy`	409	No	The wallet provider’s policy refuses the request: token, capability, destination, per-asset limit or rate. A larger USD budget or a new grant does not lift it. The owner changes the blocking rule with `policy_update`.
`policy_not_found`	`policy`	409	No	The agent wallet has no policy in force yet. Wait for onboarding or the pending policy intent.
`insufficient_balance`	`balance`	400, 409	No	The balance the request spends from (public, or confidential) holds less than it spends. Nothing was submitted or charged. `meta.available_amount` is what it can still spend, in atomic units. Fund the agent or send a smaller amount. The API checks this itself before anything is recorded and answers 400, with no history row. The provider’s own refusal answers 409. A timelocked request is checked again when it is released.
`wallet_busy`	`provider`	409	Yes, except as a recorded execution outcome	The agent wallet is running another money operation. Nothing was sent. If the response carries `meta.retryable`, send the same request again with the same key after `Retry-After`. If the refusal is the recorded outcome of an execution, this key replays it: once the other operation finishes, send the work again under a new `Idempotency-Key`.
`amount_too_low`	`request`	409	No	The amount is below the route’s minimum. Quote at least `meta.min_amount` (atomic units of the asset sent) when it is present, else a larger amount.
`route_unavailable`	`provider`	409	No	No route or liquidity is available for this asset pair or amount. Nothing was submitted. Try a different amount or pair under a new `Idempotency-Key`; repeating this request will not help.
`invalid_address`	`request`	400, 409	No	The recipient is not a valid address for this chain, or the provider refused it. Nothing was sent. A malformed address answers 400 before the policy is read, as does a `transfer` to a named NEAR account that does not exist. A dry swap or withdrawal gets the same 400 before any provider call and uses no preview attempt. A provider refusal answers 409.
`withdraw_preview_pending`	`provider`	409	Yes	A preview under this key is still running and may already have used provider capacity. Retry shortly with the same key; don’t loop with new keys.
`withdraw_preview_expired`	`request`	409	No	This key’s preview is older than 60 seconds. Preview again under a new `Idempotency-Key`.
`withdraw_preview_limit_reached`	`provider`	429	No	The agent used its 20 withdrawal previews for the rolling 24 hours. A provider refusal, an outage and an uncertain attempt stay counted; only an answer the provider gives before running anything (its rate limiter’s 429, `wallet_busy`, `provider_limit_reached`) gives its attempt back. `meta.available_at` and `Retry-After` say when the oldest attempt leaves the window. Withdraw without a fresh preview, or wait until then.
`unsupported_chain`	`request`	409	No	The provider does not route this chain. Withdrawals reach every `blockchain` value `GET /v1/tokens` lists.
`unsupported_token`	`request`	400, 409	No	This asset is not supported for this request. Use an `asset_id` from `GET /v1/tokens` that the route supports. The API answers 400 before anything is recorded for an asset the list does not show, with no history row. A dry swap or withdrawal for such an asset gets the same 400 before any provider call and uses no preview attempt. A provider refusal answers 409.
`provider_limit_reached`	`provider`	429	At `available_at`, except as a recorded execution outcome	The custody provider’s daily quota for this agent wallet is spent: 100 custody operations per rolling 24 hours, previews (`dry`) included and quotes excluded. Nothing was sent. A preview can be sent again at `available_at`; an execution’s refusal is recorded, so send the work again under a new `Idempotency-Key` at `available_at`. See Network & Quotas.
`refund_address_required`	`provider`	409	No	The route needs a refund address on the source chain, where the agent wallet has none. Nothing was sent, and no request field supplies one. Use another asset or route.
`custody_native_balance_required`	`balance`	409	No	The agent wallet cannot pay the network fee of this on-chain call. Nothing was sent.
`request_failed`	`provider`	409	No	The provider refused the request. Nothing was sent.
`provider_refused`	`provider`	409, or 400 on a deposit quote	No	The provider refused the request. On a deposit quote, `detail` carries the quote service’s own reason. Nothing was sent or charged; change the request and use a new key.

On the deposit address route, amount_too_low, route_unavailable, invalid_address and unsupported_token come from the quote and answer HTTP 400. amount_too_low carries meta.min_amount there too when the provider states the minimum. A quote the service refuses in words the API does not map to one of those is provider_refused (400) with its reason in detail. No address was created. See Funding an Agent.

Provider and broadcast failures

These are not refusals of the request. The provider or the network failed, and the request may or may not have taken effect. Never send the work again under a new key unless a status check proves nothing was sent.

Code	Layer	HTTP	Retryable	What to do
`provider_unavailable`	`provider`	503	Yes, except as a recorded execution outcome	The wallet provider or the quote service behind it did not answer. Check `GET /v1/network` (`one_click` for quotes). If the response carries `meta.retryable`, send the same request again with the same key after `Retry-After`. If it is a recorded execution outcome, nothing was submitted: send the work again under a new key once the provider reports `operational`.
`provider_response_invalid`	`provider`	502	No	The provider answered something the API could not read. Check the status of the `correlation_id` before you retry.
`provider_request_mismatch`	`provider`	502	No	The provider’s record of the request does not match what the API sent. Do not resend. Read the status and contact support with the `request_id`.
`provider_credential_invalid`	`provider`	502	No	The API’s own provider credential failed. Contact support with the `request_id`.
`provider_signature_invalid`	`provider`	502	No	The provider’s answer to a native signing request was not a valid signature. Nothing was returned to you. Contact support with the `request_id`.
`transaction_unconfirmed`	`api`	503	Yes	The transaction was broadcast but is not confirmed yet. Poll `GET /v1/status`, or send the same request again with the same key, which never sends twice. Never send it as new work.

Executions, recover and approvals

Code	Layer	HTTP	Retryable	What to do
`operation_kind_mismatch`	`request`	409	No	The `correlation_id` is not an execution of this kind
`operation_not_pending`	`request`	409	No	The operation is no longer pending. Read its status.
`operation_not_recoverable`	`api`	409	No	Only an `UNCERTAIN` execution that never reached the agent wallet can be recovered, from the API key that sent it, under a grant. Deposits cannot. Poll the status.
`operation_recovery_unavailable`	`api`	409	No	Another recovery of this execution is running. Wait and check the status.
`execution_not_cancellable`	`request`	409	No	Only a waiting `QUEUED` execution can be cancelled
`near_rpc_unavailable`	`api`	503	Yes	`transfer` only. NEAR RPC did not answer, so the recipient account could not be checked. Nothing was sent. Retry the same request shortly with the same key.
`timelock_payload_missing`	`api`	409	No	The queued execution’s stored request is missing, so it cannot be released. Contact support with the `request_id`.
`approval_not_found`	`request`	404	No	No such approval for this agent
`approval_changed`	`request`	409	No	The approval’s request changed since you read it. Read it again.
`approval_closed`	`request`	409	No	The approval is no longer pending. Read its state. Do not retry.
`approval_vote_unsupported`	`provider`	409	No	The provider lists no such wallet build for this owner on this network. Nothing was stored. Ask the operator before voting again.
`approval_signature_invalid`	`auth`	401	No	The provider refused the vote signature or its key. Generate a new vote with a live full-access key.
`approval_not_allowed`	`auth`	403	No	The wallet policy does not admit this owner key or `0s` wallet as approver. Read the policy before you vote again.
`approval_already_voted`	`request`	409	No	This account already voted. Read the approval. Do not vote again.

Owner intents and signatures

Code	Layer	HTTP	Retryable	What to do
`intent_expired`	`auth`	409	No	The signing window closed. Generate a new intent.
`intent_payload_mismatch`	`auth`	409	No	Submit `signed_data.payload` exactly as generate-intent returned it
`intent_standard_mismatch`	`auth`	409	No	Sign with the standard generate-intent returned in `intent.standard`
`intent_type_mismatch`	`request`	409	No	The submission’s `type` is not the type of this intent
`intent_not_pending`	`request`	409	No	The intent is no longer waiting for a signature. Read its status.
`intent_generation_recovery_required`	`api`	409	No	An earlier generate call with this key started but did not finish, and cannot be resumed yet. Retry with the same key and body shortly.
`signer_mismatch`	`auth`	409	No	The signature comes from a different key than the intent’s `signer`
`owner_nonce_invalid`	`auth`	409	No	This intent was already used or expired. Generate a new one.
`owner_counter_conflict`	`auth`	409	No	The owner’s signature counter did not advance, for example because two signatures raced. Generate a new intent and sign again.
`owner_epoch_invalid`	`auth`	409	No	The grant intent was signed for an earlier owner state. Generate a new intent.
`owner_mismatch`	`auth`	403 or 409	No	The signer is not this agent’s owner
`owner_type_unsupported`	`auth`	400	No	This deployment does not create agents for this owner type. `GET /v1/network` lists `supported_owner_types`.
`signature_invalid`	`auth`	400	No	The submitted signature is not in a format the signer’s wallet produces. Submit exactly what the wallet returned.
`owner_proof_invalid`	`auth`	401	No	The owner’s signature or proof does not verify. Sign the intent payload unchanged and submit the wallet’s output.
`invalid_nonce`	`request`	400	No	The owner proof’s nonce is not 32 bytes
`invalid_public_key`	`request`	400	No	The owner’s public key is not valid
`owner_key_not_full_access`	`auth`	403	No	The NEAR key is not a full-access key of the owner account
`owner_verification_unavailable`	`api`	502	No	The NEAR network could not verify the key. Try again later.
`wallet_authorization_required`	`auth`	401	No	Passkey and EVM owners must send a wallet authorization with the signature
`wallet_authorization_invalid`	`auth`	400 or 401	No	The wallet authorization is not valid. Sign again with the same wallet.
`wallet_authorization_expired`	`auth`	409	No	The wallet authorization expired. Generate a new intent.
`wallet_authorization_unresolved`	`auth`	401	No	The wallet account could not be resolved from the authorization
`wallet_resolver_unavailable`	`api`	503	Yes	The service that resolves wallet accounts is unavailable. Retry shortly.
`wallet_rpc_unavailable`	`api`	503	No	The NEAR network was unreachable. Try again later.
`owner_command_domain_invalid`	`auth`	409	No	The owner command uses a message format this API no longer accepts. Generate a new intent and sign it unchanged.
`owner_command_expired`	`auth`	409	No	The owner command expired. Generate a new intent.
`owner_command_stale`	`auth`	409	No	The owner command was signed for an earlier owner state, or it is the signature of a deletion that was later restored. Generate a new intent and sign again.
`owner_command_target_mismatch`	`auth`	409	No	The signed command’s action or target differs from the one submitted. Generate a new intent for this target.
`owner_control_expired`	`auth`	409	No	The owner control window closed. Generate a new intent.
`authorization_stale`	`auth`	409	No	The authorization is out of date, for example after a policy change. Nothing was sent. For an owner intent, generate a new one. For an action, send it again with a new key.

Policy updates

Code	Layer	HTTP	Retryable	What to do
`policy_revision_conflict`	`policy`	409	No	The policy changed since you read it. Read `GET /v1/agents/{agent_id}/policy` and generate again with its `revision`.
`policy_reconciliation_required`	`policy`	409	No	Another policy intent is still signable or settling. Wait for it to settle or expire, then generate again.
`policy_blocks_delete`	`policy`	409	No	The applied policy was signed in an older shape and cannot delete the agent. Sign a new policy with `policy_update` first.
`policy_commitment_mismatch`	`policy`	409	No	The signed policy is not the one the API prepared. Generate again.
`policy_state_conflict`	`policy`	409	No	The policy intent is already applied or in a different state. Read its status.
`policy_not_pending`	`request`	409	No	The policy intent is no longer waiting. Read its status.
`policy_owner_mismatch`	`policy`	409	No	The policy’s owner differs from the agent’s owner. A delete is refused when the owner on chain is not the agent’s owner.
`policy_provider_change_requires_relay`	`policy`	409	No	The signed change touches rules the agent wallet enforces, but was prepared as an off-chain change. Read the policy and generate the `policy_update` again.
`policy_deposit_limit`	`policy`	409	No	The policy change would need more storage than the API allows. Reduce the number of destinations.
`policy_delegate_invalid`	`auth`	400	No	The signed policy transaction is malformed. Generate again.
`policy_delegate_action_invalid`	`auth`	400	No	The signed policy transaction holds an action the API does not accept
`policy_delegate_action_mismatch`	`auth`	409	No	The signed policy transaction differs from the generated one
`policy_delegate_signature_invalid`	`auth`	401	No	The policy transaction’s signature does not verify
`policy_delegate_owner_mismatch`	`auth`	403	No	The policy transaction is signed by a different account or key than the owner’s
`policy_delegate_expired`	`auth`	409	No	The owner’s signed transaction can no longer run: it expired, its key is gone or no longer full-access, or its nonce is used. Raised on policy submissions and when you submit `agent_delete`, where it is checked before anything is retired. Generate a new intent.
`policy_storage_changed`	`policy`	409	No	The policy’s storage cost changed after the intent was generated. Nothing was sent. Generate a new intent and sign that one.
`provider_policy_mismatch`	`provider`	409	No	The wallet provider’s policy differs from the one the API expects. Nothing was sent. Read the policy and generate again.
`provider_policy_unavailable`	`provider`	503	No	The provider’s policy could not be read. Try again later.

Agent wallet state

These come from creating, restoring or deleting an agent wallet. Most mean the wallet’s on-chain state differs from what the API expects, and you cannot fix them yourself. Contact support with the request_id.

Code	Layer	HTTP	Retryable	What to do
`wallet_not_provisioned`	`api`	409	No	The agent wallet does not exist yet. Wait for onboarding.
`wallet_not_active`	`api`	409	No	The agent wallet is not active. Read the agent.
`wallet_provisioning_failed`	`api`	502	No	Creating the wallet failed. Generate a new `agent_create` intent.
`wallet_provisioning_uncertain`	`api`	409	No	Creating the wallet may have succeeded. Poll the `agent_create` status. Do not create another agent.
`wallet_network_unsupported`	`api`	409	No	This deployment cannot create wallets on this network
`wallet_code_untrusted`	`api`	409	No	The wallet runs code the API does not trust. Contact support.
`wallet_code_mismatch`	`api`	409	No	The wallet code differs from the expected version. Contact support.
`wallet_account_mismatch`	`auth`	409	No	The wallet account differs from the expected one. Contact support.
`wallet_conflict`	`api`	409	No	The wallet is in a conflicting state. Contact support.
`wallet_mismatch`	`auth`	409	No	The request refers to a different wallet than the agent’s
`wallet_policy_signer_unsupported`	`api`	409	No	The owner type cannot sign this wallet policy
`wallet_request_type_mismatch`	`auth`	409	No	The signed request is not of the expected type for this owner
`wallet_request_mismatch`	`auth`	409	No	The signed request differs from the generated one. For a delete, sign the request the delete challenge returned, unchanged.
`wallet_request_expired`	`auth`	409	No	The signed request expired. Generate a new intent.
`wallet_request_signature_invalid`	`auth`	401	No	The wallet request’s signature does not verify
`storage_funding_mismatch`	`api`	409	No	The wallet’s storage funding differs from the expected amount. Contact support.
`evm_public_key_mismatch`	`auth`	409	No	The EVM owner’s public key does not match the agent’s owner
`invalid_intents_response`	`provider`	502	No	NEAR Intents answered something the API could not read. Try again later.

Deleting an agent

A delete is one owner signature, so submitting it can also fail with agent_not_bound, policy_blocks_delete, policy_owner_mismatch, policy_delegate_expired, wallet_request_mismatch and wallet_request_type_mismatch. They are listed under Agents and lifecycle, Policy updates and Agent wallet state. The submission is refused before anything is retired. After the deletion completes, the API relays the signed policy cleanup. It cannot undo the deletion, and its outcome is details.policy_record in the status.

Code	Layer	HTTP	Retryable	What to do
`deletion_assets_remaining`	`balance`	409	No	The wallet holds a public or confidential balance that deleting would destroy, including funds that arrived after the owner signed: the API reads the balances again right before it commits. Nothing was retired. Withdraw the funds, then generate the deletion again.
`delete_submission_uncertain`	`api`	409	No	The delete may have been sent. Poll its `correlation_id`. Do not generate another delete.
`deletion_unavailable`	`api`	503	No	Deleting is not available right now. Try again later.
`operation_result_invalid`	`api`	409	No	The recorded delete result cannot be read. Contact support.

Native accounts

Code	Layer	HTTP	Retryable	What to do
`signing_recipient_forbidden`	`policy`	403	No	`intents.near` and `intents.far` can never be recipients, whatever the policy says
`native_contract_forbidden`	`policy`	403	No	A native NEAR transfer to, or call of, `intents.near` or `intents.far`. Never allowed. Use the NEAR Intents actions instead.
`invalid_hex_payload`	`request`	400	No	`message` is not valid hex although `encoding` is `hex`
`invalid_utf8_payload`	`request`	400	No	The hex `message` does not decode to valid UTF-8

Transparency

Code	Layer	HTTP	Retryable	What to do
`transparency_log_disabled`	`api`	501	No	This deployment does not run the transparency log. See Transparency Proofs.

Next steps

Executions

Run actions, and recover an uncertain one.

Policies & Limits

Understand the rules and the USD budget behind the policy errors.

Network & Quotas

Read limits, cooldowns and the health of the services behind the API.

Funding an Agent

Create deposit addresses and handle refunds.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Check a status

Status values

Status fields

List an agent’s history

Idempotency

When the result is unknown

UNCERTAIN

NEEDS_REVIEW

Budget charges and failures

Owner intents

Error format

Error layers

Error codes

Request and authentication

Idempotency

Rate limits and capacity

Agents and lifecycle

Grants

Refused by the account policy

Refused by the wallet provider

Provider and broadcast failures

Executions, recover and approvals

Owner intents and signatures

Policy updates

Agent wallet state

Deleting an agent

Native accounts

Transparency

Next steps

Executions

Policies & Limits

Network & Quotas

Funding an Agent

​Check a status

​Status values

​Status fields

​List an agent’s history

​Idempotency

​When the result is unknown

​UNCERTAIN

​NEEDS_REVIEW

​Budget charges and failures

​Owner intents

​Error format

​Error layers

​Error codes

​Request and authentication

​Idempotency

​Rate limits and capacity

​Agents and lifecycle

​Grants

​Refused by the account policy

​Refused by the wallet provider

​Provider and broadcast failures

​Executions, recover and approvals

​Owner intents and signatures

​Policy updates

​Agent wallet state

​Deleting an agent

​Native accounts

​Transparency

​Next steps

Executions

Policies & Limits

Network & Quotas

Funding an Agent

Check a status

Status values

Status fields

List an agent’s history

Idempotency

When the result is unknown

UNCERTAIN

NEEDS_REVIEW

Budget charges and failures

Owner intents

Error format

Error layers

Error codes

Request and authentication

Idempotency

Rate limits and capacity

Agents and lifecycle

Grants

Refused by the account policy

Refused by the wallet provider

Provider and broadcast failures

Executions, recover and approvals

Owner intents and signatures

Policy updates

Agent wallet state

Deleting an agent

Native accounts

Transparency

Next steps