Skip to main content

Refusal reasons

Before a wallet pays, Keyban evaluates the payment against the wallet policy, the destination rules and the organization's limits. The decision is allow, deny or require_human. A deny carries one or more reasons that start with policy/; so does a require_human, which holds the payment until a wallet operator approves it. This page lists every reason the backend can return, and what an agent should tell the user for each.

How to read this page​

  • A reason can be followed by details, as in policy/amount-exceeded: 1500 > 1000. The reason is the part before the colon.
  • A payment that breaks several rules is refused with several reasons at once.
  • A reason written between angle brackets stands for a family: policy/budget-<label>-exceeded covers policy/budget-day-exceeded, policy/budget-week-exceeded and policy/budget-month-exceeded.
  • The agent should report the reason in plain words and drop the payment. It should never split a payment into smaller ones to stay under a cap or an approval threshold, and never route a payment around a destination rule.

Reasons the backend returns​

The list below is generated from the backend code. Each reason has a row in the next section.

Reason
policy/<label>-<scope>-denylisted
policy/<label>-<scope>-not-allowed
policy/account-mismatch
policy/amount-exceeded
policy/budget-<label>-<kind>-exceeded
policy/budget-<label>-exceeded
policy/budget-currency-mismatch
policy/client-hash-mismatch
policy/destination-rule-mode-flip-needs-explicit-lists
policy/emergency-stop
policy/envelope-exceeded
policy/intent-abandoned
policy/intent-already-consumed
policy/intent-declined
policy/intent-expired
policy/intent-failed
policy/intent-in-flight
policy/intent-not-found
policy/intent-pending
policy/invalid-intent-state
policy/missing
policy/mission-required
policy/mission-run-not-active
policy/mission-run-not-found
policy/no-funding-source
policy/revalidation-required
policy/sponsor-not-applicable
policy/terms-not-accepted
policy/threshold-exceeded
policy/transaction-quota-reached
policy/wallet-not-deployed
policy/x402-asset-mismatch
policy/x402-bad-status
policy/x402-chain-mismatch
policy/x402-invalid-pay-to
policy/x402-malformed
policy/x402-no-exact-accept
policy/x402-no-x402
policy/x402-over-max
policy/x402-unknown-usdc-chain
policy/x402-unreachable

What to tell the user​

ReasonWhat it meansWhat to tell the user
policy/<label>-<scope>-denylistedThe destination is on a deny list. <label> is recipient for a transfer and domain for an x402 service; <scope> is the level of the rule: mission, wallet, application or organization.The destination is blocked at that level. Do not retry or look for a way around it; the user decides whether to change the rule.
policy/<label>-<scope>-not-allowedThe wallet has an allow list at that level and the destination is not on it.Pick a destination the list names, or ask the user to add this one. For the mission scope, the mission is updated with update_mission, played as a trial, and published by the user.
policy/account-mismatchThe address the agent said it would pay from is not the address of the wallet its API key belongs to. Nothing was paid.Tell the user the agent is not configured for the wallet it was given, and stop.
policy/amount-exceededThe payment is above the wallet's per-payment cap.Tell the user the amount is above the cap. They can raise it on the wallet page.
policy/budget-<label>-exceededThe budget of the period is used up. <label> is day, week or month.Tell the user the budget is used. They can wait for the period to roll over or raise the budget on the wallet page.
policy/budget-<label>-<kind>-exceededA monthly budget above the wallet would be overrun. <label> is the level, application or organization. <kind> is month when the budget of that level is used up, or free-share when the wallet has no budget of its own and the free share of its parent (what the parent keeps after its children's budgets) is used up. Raised whatever the wallet's own budgets say.Tell the user which level stopped the payment. An Owner or Admin can raise the budget of the application, or give the wallet a budget of its own; only an Owner can raise the budget of the organization. Otherwise it resets on the 1st of next month, in the time zone of the organization. See Control spending.
policy/budget-currency-mismatchA monthly budget above the wallet is in another currency than the policy of the wallet. Under budgets, an organization has a single currency, its display currency.Tell the user the wallet policy must be set in the display currency of the organization before it can pay, and ask an administrator to fix it. Do not retry.
policy/client-hash-mismatchA transfer's fingerprint computed by the agent differs from the one Keyban computed. Nothing was signed.Tell the user the payment could not be verified and was not made. Do not work around it; if it repeats, report it to Keyban.
policy/destination-rule-mode-flip-needs-explicit-listsA destination rule changes between allow and deny while it already holds a list the update leaves out. Returned to the assistant that changes the rule, not to a paying agent.Send the lists again with the new mode, or send null to clear one.
policy/emergency-stopThe wallet is paused, either by a person or because the free trial of the organization has ended.Tell the user the wallet is paused. If a person paused it, they resume it on the wallet page. If the free trial has ended, they upgrade the plan in Billing, which reactivates the wallet.
policy/envelope-exceededThe payment would take the spent total of a mission run above its run envelope. The key in the details is the run's id.Report it. Finish or abandon the run, or ask the user for a mission with a larger run envelope. Never split the payment.
policy/intent-abandonedThe payment was withdrawn, for example by the agent with cancel_intent.Start a new payment if the user still wants it.
policy/intent-already-consumedThe approved payment was already sent.Do not send it again. Tell the user it went through; list_expense_transactions gives its transaction hash.
policy/intent-declinedA wallet operator declined the payment.Tell the user it was declined, and send it again only if they ask.
policy/intent-expiredThe authorization lapsed before the payment was signed.Start the payment again.
policy/intent-failedThe payment ended in a failed state.Tell the user it failed, and check the wallet's transactions before paying again.
policy/intent-in-flightAn earlier USDC transfer of the wallet is still pending.Wait for it, or withdraw it with cancel_intent.
policy/intent-not-foundKeyban has no evaluated payment matching the one being signed.Start the payment again from the beginning. If it repeats, tell the user.
policy/intent-pendingThe payment waits for a wallet operator's approval.Tell the user to approve it in the Keyban dashboard Inbox, and call wait_for_intent in the same message.
policy/invalid-intent-stateThe state filter of list_wallet_payment_history is not a payment state. Returned to the assistant that lists payments.Use one of pending_human_approval, approved, declined, abandoned, consumed, expired or failed.
policy/missingThe wallet has no policy, so it cannot sign.Ask the user to open the wallet page. Do not retry.
policy/mission-requiredThe wallet's policy only pays inside a mission run, and the payment named none.Pay inside a run of the mission the task belongs to: start one if none is active, or ask the user which mission it is. If no mission is published for the task, tell the user: a person publishes one in the dashboard, or an Owner or Admin turns off the requirement. Never start a run of an unrelated mission to get the payment through.
policy/mission-run-not-activeThe mission run cannot pay. The details give its status, expired once its deadline passed, or currency_mismatch when the wallet's currency changed after it started.Tell the user the status. Wait for approval, or start a new run; never reuse an ended run. After a currency change the user must recreate the mission in the new currency.
policy/mission-run-not-foundThe run id is unknown or belongs to another wallet.Check the id with list_mission_runs; do not guess another.
policy/no-funding-sourceNo funding source is configured for the wallet. This is a default of the resolver and is not expected in normal operation.Tell the user and report it to Keyban.
policy/revalidation-requiredThe payment was approved, but its value rose above the approved value plus the wallet's volatility margin before signing. It goes back to waiting for approval.Tell the user to approve it again in the Inbox, and call wait_for_intent.
policy/sponsor-not-applicableThe Keyban welcome offer does not cover this payment. The wallet's own funds are tried next, and their reason is the one returned if they cannot pay either.Nothing to do on its own.
policy/terms-not-acceptedThe Keyban welcome offer would pay this x402 payment, but the organization has not accepted Keyban's terms and conditions yet. The wallet's own USDC does not pay in its place.Ask the user to accept the terms in the Keyban dashboard (the welcome flow shows them), then retry. Do not suggest funding the wallet for this.
policy/threshold-exceededThe payment is above the wallet's approval threshold, so it is held rather than refused.Tell the user to approve it in the Inbox, and call wait_for_intent.
policy/transaction-quota-reachedThe organization's monthly transaction quota is used up, for every wallet of the organization, until the 1st of next month (UTC).Do not retry. Ask an organization admin to upgrade the plan, or on a plan that allows it, allow billed overage in Billing, under Usage (on the Free plan, only an upgrade).
policy/wallet-not-deployedThe wallet has no address yet: it is still being deployed, or its deployment failed. Nothing can pay for it.Tell the user the wallet is not ready. Try again later, and ask the user to check the wallet if it stays that way.
policy/x402-asset-mismatchThe seller asks for a token other than the canonical USDC of the wallet's chain.Pick another provider.
policy/x402-bad-statusThe seller answered with an HTTP status other than 402 or 200, a body that is too large, or a 429.Pick another provider, or try again later if the details show a 429.
policy/x402-chain-mismatchThe seller accepts payment only on a chain other than the wallet's.Pick another provider.
policy/x402-invalid-pay-toThe recipient the seller advertises is not a valid EVM address.Pick another provider.
policy/x402-malformedThe seller answered in x402 but the answer is malformed.Pick another provider.
policy/x402-no-exact-acceptThe seller offers no exact payment scheme; the wallet cannot settle any other scheme.Do not retry. Pick another provider and tell the user.
policy/x402-no-x402The seller's answer is not an x402 payment request.Pick another provider.
policy/x402-over-maxThe price is above the maxAmount the agent set.Tell the user the price and ask whether to raise the maximum.
policy/x402-unknown-usdc-chainThe seller's network is not a chain with a known USDC.Pick another provider.
policy/x402-unreachableThe seller did not answer, after a retry.Pick another provider, or try again later.