Errors and reason codes

HTTP tool results. This page describes the full reply that POST /tools/:tool returns: error.code, reason codes, purchase.state and next.action. An MCP agent does not receive these tool-result fields. If you build an MCP agent, read Replies and next steps instead. It lists each situation, money and retry value and what to do.

Over MCP, a tool-result failure is a plain sentence for the user, a What to do line, retry and support_ref. Envoy keeps the codes in the result's _meta["money.envoy/support"] for support and hosts. Give the user the support_ref and support can find the code.

Before an MCP tool call starts, an authentication refusal is an HTTP 401 transport response, not a tool result. Read WWW-Authenticate to find Envoy's sign-in metadata. Its body has AUTH_REQUIRED for a missing or invalid bearer, or INSTALLATION_PROOF_REQUIRED when a key-bound connection lacks a valid proof. The body request_id matches the X-Request-Id header. Renew a rejected bearer once if the host has a refresh token; otherwise reconnect. For a proof refusal, use a fresh proof from the original installation. If that key is lost, reconnect as a new connection. See Request protection.

A failed call usually changed nothing. When its next reads a purchase (for example UNAVAILABLE after a write), the write may have happened. Read that purchase first. Never start a new one, because Envoy may already hold the first. The reply always says what to do next.

Support revision: envoy@2026-10. Last updated: 1 November 2026.

How an error reaches you over HTTP

The HTTP reply also has the HTTP status below. next.instruction is for the agent. error.message and purchase.status_text are safe to show the user.

Reconcile before you pay again

Never pay twice. This outranks every retry rule on this page.

• After a lost reply or timeout, read get_purchase_status before any further payment. If you cannot tell whether checkout completed, report failed with failure_reason: other. See Recover a purchase.
• When the reason is ORDER_OUTCOME_UNKNOWN, the purchase result is not known. Tell the user to contact Envoy support in the app. Do not pay again or restart.
• While the state is verifying, money is unsettled: keep reading status as next directs.
• Retrying start_purchase with the same idempotency_key continues the same purchase. A new key is a new purchase.

Error codes

When an error concerns an existing purchase, the reply includes it and next reads that purchase with get_purchase_status. Otherwise next.action is the one shown. The full table with the agent's instruction for each code is in the reference. Each code has its own heading in Each error code.

Each error code

Each heading below is a link target for one code.

INVALID_INPUT

An input field broke a rule. error.fields lists up to 10 fields with path, problem and expected. Fix all of them, then call the same tool once more. Over MCP this reads retry after_fix and a fix list.

submit_answer also refuses an answer that looks like a one-time code or holds card details, unless the open question asks for the user's merchant login. Envoy never echoes the refused value. If Envoy cannot tell which question the answer is for, error.fields names the open question's id. Ask the user again, then send the answer with that question.

UNAUTHENTICATED

The access token is missing, expired or revoked. Renew once with your refresh token if you hold one. If you cannot renew, the user reconnects Envoy through the host. A reconnect proves who you are and changes no purchase. See Reconnect and resume your task.

NOT_ALLOWED

This connection may not do that. Tell the user. Do not retry.

SERVICE_NOT_ENABLED

The purchase service is not enabled for this user or host. Tell the user. Do not retry.

NOT_FOUND

The reference does not match a purchase for this user. The reference is wrong for this user. The purchase is not gone. It also covers a purchase owned by someone else. Check the purchase_id or idempotency_key from this task. Do not start a new purchase.

IDEMPOTENCY_CONFLICT

The idempotency_key was used before with different input. Resend the original input unchanged, or read the existing purchase. Use a new key only for a different purchase. For submit_answer, the same key with a different answer returns this code.

ACTIVE_PURCHASE_EXISTS

The reply carries a user_action with task resolve_active_purchase and the message "You already have a purchase in progress. Finish or cancel it in the Envoy app first." Show it and stop. Do not start another purchase. Find the active purchase with get_account; see Recover a lost purchase reference.

STATE_CONFLICT

The call does not fit where the purchase is now. Common cases:

• report_checkout_result before the purchase is ready.
• cancel_purchase on a purchase that already completed or failed.
• submit_answer with a question that is no longer the open one. Envoy has moved on. Call get_purchase_status and read the new question. Never send the old answer to the new question.
• submit_answer with type details when no question is open.
• submit_answer with type feedback while the purchase is still in progress. Feedback is optional and never blocks checkout.

Do not retry the call. Read the purchase and follow its next.

NO_RAIL

Nothing exists to cancel or recover. error.reason_code is the rail reason, for example RAIL_AMOUNT_OUTSIDE_CARD_LIMITS. Tell the user using error.message. Do not retry or split the purchase into smaller ones. See Rail reasons.

RATE_LIMITED

You sent too many requests for this access token. Wait next.after_seconds, then repeat the same call unchanged. Add jitter and back off if you see it again. See Retry after a 429.

UNAVAILABLE

Envoy or an upstream service is unavailable. If next calls get_purchase_status with your original reference, the write may or may not have happened. Read the purchase before anything else. If error.retryable is true, wait next.after_seconds and repeat the same call. If it is false, tell the user to try again later. Never pay another way meanwhile, because the first purchase may still complete.

CLIENT_UPDATE_REQUIRED

This client is too old (HTTP 426). Tell the user to update it.

Reason codes

purchase.reason_code says why a purchase is in its state. A reason code never arrives alone. It arrives in one of three places:

• On purchase.reason_code, next to a purchase.state. Most reasons in the first two tables below.
• On error.reason_code, next to the error code NO_RAIL. Only rail reasons.
• On purchase.rail_reason, which says which payment path Envoy chose. Not an error.

Over MCP the reason shapes the briefing's wording and appears only in _meta. The agent never sees the code. The meaning below is the sentence Envoy shows as purchase.status_text, safe to show the user.

The Arrives with column comes from Envoy's state mapping and the service code. "Reserved, not sent today" means the contract lists the code but no service path produces it yet. The contract only adds codes and never removes them, so a reserved code stays listed. Handle it by its meaning, in case it starts to appear.

Policy and user decisions

Order outcomes

Over MCP, a purchase that Envoy refused after the user approved it reads "Envoy couldn't complete this payment after you approved it". It does not say "your spending settings do not allow this purchase", because the user's settings are not the cause.

ORDER_OUTCOME_UNKNOWN is the recovery reason. It arrives with state verifying. Keep reading status as next directs. Never pay again. If next.action becomes stop, tell the user to contact Envoy support in the app.

A failure_reason in report_checkout_result (card_not_accepted, card_declined, otp_failed, price_changed, out_of_stock, site_error, site_blocked, other) records what you saw. Like every report, it moves a ready purchase to verifying until Envoy has money evidence. If you cannot tell whether checkout completed, report failed with failure_reason: other. Envoy refuses agent cancellation after a report unless it reopens the card with a new ready handout.

Rail reasons

purchase.rail_reason says which payment path Envoy chose. With NO_RAIL, error.reason_code says why Envoy could not pay, and error.message repeats the meaning. Envoy chooses the path for each purchase. The agent can use a one-time card or paid gift-card voucher, or Envoy checks out itself. purchase.checkout_by carries the result; see Read checkout_by to know who pays. Do not predict the path from a rail reason.

The generated reason-code reference lists the exact current values and reserved codes. It includes host restrictions, merchant gateways, gift cards and available marketplace offers. A declared value does not mean that its route is enabled for this account.

For a refusal, use error.message and follow next. For a selected route, read the latest checkout_by. Never infer permission to pay from a reason code alone.

States and next.action

Every purchase reply has a purchase.state and a next.action. This table shows the pair for all ten states. Over MCP the agent reads situation instead; see Replies and next steps.

A held state changes to stop after four unchanged held reads or when next.by passes. Stop waiting then, and do not pay. The Envoy app shows the user the result.

The other next.action values come with errors and reads: fix_input, retry, reconnect, update_client, stop (see the error table) and continue (a successful read such as get_account).

Related

• Recover a purchase
• Replies and next steps
• Shared schemas
• Frequently asked questions