Browse the docs

Coded Tool Errors and next_step

The MCP tool error envelope, when to retry, and every error code with what to do next.

When a Moon MCP tool cannot do what it was asked, it does not fail the protocol call. It answers normally, with a result marked isError: true whose single text block is a JSON error envelope: a stable code to branch on, and a next_step sentence that tells the agent what to do about it. This page is that contract, and the list of codes.

It applies to the MCP server only. The REST API uses its own error envelope.

The envelope

Field	Meaning
`code`	Stable, lower-case, and the thing to branch on. It does not change once published
`message`	What happened, for a person or a log. Its wording can change — do not parse it
`next_step`	One or two sentences telling the agent what to do next, naming the tool to call. Written to be followed as-is
`details`	Structured facts about the failure — the fields that failed validation, the balance available, the status an approval is in. Omitted when there are none
`retryable`	`true` only when repeating the same call can succeed

details never contains a card number or security code, whatever raised the error, and any run of digits shaped like a card number is replaced with [redacted] in message and in string details.

How to handle a refusal

Branch on code. Two refusals can share a message and mean different things, and the same refusal can be reworded.
Follow next_step. It is the recovery path Moon would take, and it names the tool.
Retry only when retryable is true, and then with the same idempotency_key. A retry with the same key replays the first answer, so it can never issue a second card or top up twice. Never retry a false: the same call will get the same answer.
Do not loop. Several refusals mean wait for a person (purchase_intent_not_usable with AWAITING_APPROVAL — call wait_for_approval) or ask a person (INTENT_REQUIRED declines). Calling again does not make a person answer faster.

retryable is true for a Moon-side failure (internal_error), for rate limiting (too_many_requests) and for idempotency_in_progress, where the first call with that key is still running. It is false for everything else.

Failures outside the envelope

Failure	What you receive
No usable credential, or an unsupported HTTP method	A real HTTP `401` or `405`, before any tool runs. The `401` carries a `WWW-Authenticate` challenge — see MCP Server
Maintenance, an oversized request or batch, a restricted account, a rate limit	A JSON-RPC error before any tool runs, whose `error.data` carries `code`, `message`, `next_step` and `retryable` — for example `rate_limited` with `Retry-After`. See Limits
Arguments that do not match a tool's advertised schema	A result with `isError: true` whose text is plain, not JSON, and starts with `Input validation error:`. Treat any `isError` text that does not parse as JSON as this case
A tool behind a permission an OAuth connection lacks	Inside the envelope: `insufficient_scope`, with `details.missing_scopes`. The tool is listed in `tools/list` with a line naming the permission, and never runs. See What the agent sees when a tool is missing

Codes

Arguments and lookups

Code	Meaning	`next_step` in short
`validation_error`	An argument failed a rule the tool checks itself. `details.errors` lists `{ path, message }` for each	Fix the named arguments and call again
`bad_request`	The request was refused for a reason with no more specific code	Check the arguments and retry
`card_not_found`	No such card for this connection. On a cardholder connection, a card belonging to someone else answers this too	Check the id, or call `list_cards`
`cardholder_not_found`	No such cardholder	Check the id, or `create_cardholder` first
`not_found`	Something else named in the call does not exist	Check the id you passed
`cardholder_id_and_end_customer_id_exclusive`	`create_card` got both	Pass one of them
`velocity_control_target_required`, `cardholder_status_target_required`	A status read needs exactly one target	Pass exactly one of the named arguments
`amount_cannot_be_negative`	A negative amount	Pass a positive amount

Money and verification

Code	Meaning	`next_step` in short
`kyc_required`	The cardholder (or your organization) is not verified. `details.source_code` keeps the original code	`create_cardholder_kyc_link`, share it, poll `get_cardholder_kyc_status`
`cardholder_bank_kyc_not_approved`, `cardholder_required_for_issuer`	A verification gate specific to the card product	Same as `kyc_required`
`moon_card_agreement_not_accepted`	The cardholder has not accepted the card agreements	The cardholder accepts them first

Cards and controls

Code	Meaning	`next_step` in short
`card_product_not_supported`	The card product does not support this	Pick another from `list_card_products`
`merchant_lock_unsupported`	The product cannot carry a merchant lock	Pick one from `details.merchant_lock_card_product_ids`, or drop `merchant_lock`
`merchant_lock_not_found`	The card has no lock to change	Set the lock when the card is issued
`control_is_fixed`	The control belongs to a card feature (single-use, merchant lock, ask-first)	Use the card-level tool, or `terminate_card`
`velocity_control_already_exists`	The target already has a control	Find it with `list_velocity_controls` and update it
`velocity_control_reserved_metadata_key`	`fixed` is a reserved metadata key	Remove it
`velocity_control_reserved_type`	`INTENT` is not a type you create	Use `enable_ask_first`
`agent_cards_must_ask_first`	The account owner requires every card a connected agent creates to ask first	`create_card` without `ask_first` — it is issued asking first — then `request_purchase` for each purchase. Do not ask the person to turn the setting off

Ask-first cards and purchase intents

Code	Meaning	`next_step` in short
`card_not_ask_first`	`request_purchase` on a card that spends on sight	`enable_ask_first` if that is what you wanted
`approval_email_missing`	Nobody can be asked. `details.approver_type` says whose address is missing	Give the cardholder, or the account, an email address
`purchase_intent_currency_mismatch`	`currency` is not the card's own	Omit it, or send the card's currency
`merchant_currency_unsupported`	The price was given as `merchant_amount` + `merchant_currency`, and Moon has no rate to convert that currency into the card's right now. Nothing was created	Ask again with `amount` in the card's own currency (`details.card_currency`): read the card-currency price off the checkout if it shows one, or convert it yourself and add a tolerance for the difference. Not retryable as-is
`purchase_intent_not_pending`	The intent was already answered, spent, cancelled or expired	Read it with `get_purchase_intent`; ask again if the purchase still has to happen
`purchase_intent_decision_invalid`	A decision other than `approve` or `deny`	Pass what the person actually said
`too_many_pending_intents`	The card holds as many live approvals as it may	Cancel one you no longer need, or wait for them to expire
`too_many_recurring_approvals`	The card holds as many standing approvals as it may	Cancel one — waiting will not clear it
`purchase_intent_required`	`reveal_card_credentials` on an ask-first card	`request_purchase`, wait, then `get_payment_credential`
`purchase_intent_not_usable`	The approval cannot be paid with now. `details.status` says why	`AWAITING_APPROVAL`: `wait_for_approval`. Anything else: ask again
`too_many_credential_reveals`	This approval has handed the number over as often as it may	Ask for a new approval; call `get_payment_credential` once per purchase

Checkout details

These come from request_purchase with profile_fields, and from get_checkout_details.

Code	Meaning	`next_step` in short
`checkout_profile_field_missing`	A detail named in `profile_fields` is not saved. `details.missing` names it	The person adds it at `/settings/checkout-details`, then ask again. Never ask them to type it to you
`merchant_domain_required_for_profile`	`profile_fields` without `merchant_domain`	Ask again naming the site
`profile_fields_not_allowed_on_recurring`	`profile_fields` on a recurring approval	Use a single purchase or `kind: "order"`, or leave the fields out
`profile_field_not_fillable`	The national ID on file is a type that cannot be filled	Ask again without `national_id`; the person enters it at checkout
`profile_reveal_not_enabled`	An API-key connection has not opted in to receiving approved details	Send `x-moon-allow-profile: true`. On OAuth, the `profile:reveal` permission takes its place
`checkout_details_not_available`	The account does not release checkout details to agents	The person enters them at checkout
`checkout_details_not_for_this_connection`	The approval was requested by another connection	Only the connection that asked receives the details
`profile_fields_not_approved`	The approval did not name the details asked for. `details.not_approved` lists them	`request_purchase` naming them in `profile_fields`
`checkout_profile_changed`	The details changed after the person approved	`request_purchase` again and wait for a new approval
`too_many_profile_releases`	This approval has released its details as often as it may	Ask for a new approval; the count never resets

Permissions and connections

Code	Meaning	`next_step` in short
`reveal_not_enabled`	An API-key connection has not opted in to card numbers	Send `x-moon-allow-pan: true`. On OAuth the permissions `cards:pay` (`get_payment_credential`) and `cards:reveal` (`reveal_card_credentials`) take its place
`insufficient_scope`	The connection was not granted the permission this needs. `details.missing_scopes` names it	Ask the client to reconnect with that permission — a one-step re-approval. If it cannot, the person reconnects at Settings → Connected apps (`/settings/connected-apps`), approving it
`forbidden`	This connection may not perform that operation	Use a connection that may
`unauthorized`	The credential is not valid for this	Check the bearer
`invalid_agent_signature`	A signed request did not verify. Never says which check failed	Check `keyid`, the time window, the nonce and the covered components — or send the request unsigned
`agent_key_invalid_jwk`, `agent_key_already_registered`, `agent_key_not_found`	Agent-key administration refusals	Send a public Ed25519 JWK; reuse the existing `key_id`; check the id

Idempotency, environment and Moon-side failures

Code	Meaning	`retryable`	`next_step` in short
`idempotency_in_progress`	The first call with this key is still running	`true`	Wait a moment, retry with the same key
`idempotency_mismatch`	The key is bound to different arguments	`false`	Use a new key, or resend the original arguments
`conflict`	The resource is in a state that refuses this call	`false`	Read it back before retrying
`too_many_requests`	Rate limited	`true`	Wait, then retry with the same key
`internal_error`	Moon failed	`true`	Retry once with the same key; then contact support

A code not listed here falls back to the same rules: a code ending in _not_found means check the id, and anything else is answered with a next_step that says whether to fix the arguments or retry. New codes are added without notice as tools are added, so handle an unknown code by following next_step rather than failing.

When money may already have moved

create_card and add_card_balance take an idempotency_key. If a call fails after the money-moving step began, the key is bound to that failure and a retry with the same key replays the failure rather than running again; the next_step then tells the agent what to read — list_cards, or the card's balance — before deciding whether to try again with a new key. That is what keeps one unlucky attempt from becoming two funded cards. A call refused before any money moved releases its key, so the same key works once the cause is fixed. See MCP Server.

MCP Server — the tools, connections and permissions.
Purchase intents — what the ask-first codes are about.
Errors — the REST API's error envelope, for comparison.

Last updated October 22, 2026