Troubleshooting and support
Find your symptom, follow the reply's next step, and reach support when the outcome is unclear.
Over MCP, every result starts with a briefing. Follow its What to do line first. Over HTTP, every failed reply has an error.code and a next. Follow next first. Keep the purchase reference. A timeout never authorizes another payment.
Support revision: envoy@2026-10. Last updated: 28 October 2026.
| Symptom | Next step |
|---|---|
| Signed out, token expired or revoked, wrong account | Reconnect and resume your task. For sign-in codes and tokens, see Credentials and secrets. |
| You want to end an agent's access | Disconnect an agent. This does not cancel an open purchase. |
| The host lists the wrong tools | Refresh a stale tool list |
| Lost reply, failed checkout step or uncertain purchase | Recover a purchase |
| The purchase does not start, or the user must finish identity checks | KYC does not finish |
Too many requests (HTTP 429) | Retry after a 429 |
| An error or reason code you do not recognize (REST only) | Errors and reason codes |
| A question this page does not answer | Frequently asked questions |
An MCP agent never sees error codes. It sees a briefing, retry and support_ref. See Replies and next steps. The error and reason code tables are for HTTP clients.
KYC does not finish
KYC is the identity check that unlocks purchases. It has two levels: min-KYC and full-KYC. The user completes it only in the Envoy app. The agent cannot start, check or finish it, and no tool reports its status. Read KYC and eligibility for what each level allows.
If the user's KYC fails or is incomplete:
- Tell the user, in plain words, that Envoy needs them to finish identity checks in the Envoy app. The agent cannot fix this itself.
- Ask the user to open the Envoy app and retry KYC there.
- After the user says it is done, call
get_account, then start the purchase again. - Do not start a second purchase to work around it, because the first may still be waiting. Check
active_purchaseinget_accountfirst.
If the user retries and KYC still fails, send them to support with the steps below. The support_ref from the stalled reply helps support find the request.
Contact support
Envoy has no status page. Contact support for any outcome you cannot resolve.
- Use envoy.money/support, or email support@envoy.money. The support page also lists the grievance escalation contact.
- Refunds: A failed payment does not prove that money returned. Read the returned money status and contact support if the outcome stays unclear. Merchant refunds follow the merchant's policy. While money is unknown, the agent never pays again.
- Contact the merchant for order or delivery questions.
Quote the support reference, support_ref (for example EV-72Z0SF), from the result. Support finds the request with it. Over HTTP, include the error code and the reply's request_id and trace_id instead.
Also include:
- The purchase reference (
purchase_idoridempotency_key). - The approximate time.
- The step that failed.
Never send tokens, OTPs, card details or full tool replies. Feedback sent with submit_answer is product feedback, not support.
Check that the service is up
The API health endpoint reports whether the service is up. ok there means the service is up. It does not mean a connection or purchase succeeded, or that a merchant order went through. Use get_purchase_status for a purchase. If the health check fails, keep the purchase reference and contact support.