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>-exceededcoverspolicy/budget-day-exceeded,policy/budget-week-exceededandpolicy/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
| Reason | What it means | What to tell the user |
|---|---|---|
policy/<label>-<scope>-denylisted | The 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-allowed | The 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-mismatch | The 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-exceeded | The 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>-exceeded | The 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>-exceeded | A 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-mismatch | A 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-mismatch | A 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-lists | A 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-stop | The 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-exceeded | The 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-abandoned | The payment was withdrawn, for example by the agent with cancel_intent. | Start a new payment if the user still wants it. |
policy/intent-already-consumed | The 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-declined | A wallet operator declined the payment. | Tell the user it was declined, and send it again only if they ask. |
policy/intent-expired | The authorization lapsed before the payment was signed. | Start the payment again. |
policy/intent-failed | The payment ended in a failed state. | Tell the user it failed, and check the wallet's transactions before paying again. |
policy/intent-in-flight | An earlier USDC transfer of the wallet is still pending. | Wait for it, or withdraw it with cancel_intent. |
policy/intent-not-found | Keyban has no evaluated payment matching the one being signed. | Start the payment again from the beginning. If it repeats, tell the user. |
policy/intent-pending | The 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-state | The 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/missing | The wallet has no policy, so it cannot sign. | Ask the user to open the wallet page. Do not retry. |
policy/mission-required | The 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-active | The 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-found | The run id is unknown or belongs to another wallet. | Check the id with list_mission_runs; do not guess another. |
policy/no-funding-source | No 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-required | The 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-applicable | The 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-accepted | The 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-exceeded | The 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-reached | The 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-deployed | The 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-mismatch | The seller asks for a token other than the canonical USDC of the wallet's chain. | Pick another provider. |
policy/x402-bad-status | The 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-mismatch | The seller accepts payment only on a chain other than the wallet's. | Pick another provider. |
policy/x402-invalid-pay-to | The recipient the seller advertises is not a valid EVM address. | Pick another provider. |
policy/x402-malformed | The seller answered in x402 but the answer is malformed. | Pick another provider. |
policy/x402-no-exact-accept | The 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-x402 | The seller's answer is not an x402 payment request. | Pick another provider. |
policy/x402-over-max | The price is above the maxAmount the agent set. | Tell the user the price and ask whether to raise the maximum. |
policy/x402-unknown-usdc-chain | The seller's network is not a chain with a known USDC. | Pick another provider. |
policy/x402-unreachable | The seller did not answer, after a retry. | Pick another provider, or try again later. |