Troubleshooting

Find the symptom below, apply the suggested check, then retry the action that failed.

Where you are stuck	Start here
Signing in to Platform	Sign-in checks
Connecting or syncing data	Connection checks
Connecting an assistant	MCP checks
Calling the API	API errors
Reading order information	Order states

Use the email address provisioned for your organization. Requesting a magic link does not create access. Check your inbox and spam folder; if the link is invalid or expired, request a new one from Platform.

If you see a rate-limit message, wait for the indicated time before requesting another link. If signing in still leaves you without access, ask your administrator to confirm your membership and permissions.

A connection is missing or has not synced

Open Connections or Connectors → Shopify and refresh the status. A connected label or “Sync started” message does not confirm a successful sync. Check Last success and any displayed error code.

If a save was not confirmed, reload before submitting again: it may have succeeded. If the Shopify setup form is missing, check for an existing store, including a disconnected one. Restoring that connection requires administrator assistance. See Connect your sources.

MCP will not connect or shows no tools

Symptom	What to check
Connection fails	Use `https://api.meetwillow.cx/api/v1/mcp` and Streamable HTTP. Opening that URL as a browser page is not a connection test; the MCP endpoint accepts POST requests.
Sign-in repeats	Re-authenticate from the client and confirm your EcomSquad membership is still active. Remove any stale `x-api-key` header when using OAuth.
No tools appear	The key or approved sign-in scopes may lack `context:read`. Check the permissions used by this connection.
Read tools appear, but no refresh tool	`refresh_ticket` requires `context:refresh`. Reading does not require it.
A previously available tool is now “not found”	Permissions may have changed. Reconnect or refresh the client’s tool list.
Tools work but return no tickets	Check the key’s mailbox connection access, any filters, and whether conversations have arrived.

Some older API keys created before the Context API was available lack context:read, even if they were originally created from a read-only preset. Create a replacement with the current permissions using API keys.

API requests fail

Result	Next step
`UNAUTHORIZED` / HTTP 401	Check that `x-api-key` contains a valid EcomSquad API key that has not expired or been revoked. An EcomConnect agent key will not work.
`FORBIDDEN` / HTTP 403	The message names the missing permission. Authenticating does not grant every action.
`NOT_FOUND` / HTTP 404	Use an ID from a ticket list returned by the same credentials. A conversation ID is not a ticket ID. The record may be missing or outside your organization’s or key’s connection access.
`BAD_REQUEST` / HTTP 400	Check the input against the API Reference, including UUIDs, page limits, and supported filters.
An empty `items` array	Check filters, mailbox sync, and connection limits. An empty result is not proof that your organization has no data.

MCP tool failures can arrive inside an HTTP 200 response. Check the tool’s error result, not only the HTTP status.

Order context is missing or stale

Reads return what is stored. Check the ticket’s orders: an order’s details is null until the orders sync or a store lookup has stored it, and its items stay empty until a lookup has. If the answer needs what is missing, refresh the ticket and check refresh.state:

`refresh.state`	Next step
`none`	If `refresh.skipped` is above zero, refresh again. Otherwise ask for an order number.
`not_found`	Read `refresh.attempts` to see which lookup failed. If the ticket names no order, ask for an order number.
`outside_history`	Ask the merchant to locate the order.
`access_missing`	Ask your administrator to check the store connection.
`provider_unavailable`	Wait a few minutes, then refresh.
`not_permitted`	Ask for a key or access that includes the store connection as well as the mailbox.

See Tickets for what each state means and how lookups decide it.

Check the fix

Repeat the original sign-in or read with the same organization and intended connections. For sync problems, look for an updated Last success time. For ticket reads, inspect the returned orders as well as the request status.

Still stuck?

Send your administrator the action you tried, the time, the displayed error code, and the connection label if relevant. Mention whether the problem happens in Platform, your assistant, or a REST request. Do not include API keys, sign-in links, customer message bodies, or full API responses.