Limits, errors and troubleshooting

The MCP server has no error catalog of its own: every tool forwards the real response from /public/v1, so the envelope, the codes and the limits are exactly the public API’s — Errors and Plans and limits are the full reference. This page translates the most common cases into “what to do” when the failure shows up inside your MCP client.

How an MCP client sees an API error

When a tool fails, your client gets a response with isError: true and the same JSON body the API would return — the error field is the only one you should use to decide what to do, same as with the API directly:

{
  "error": "PERMISSION_DENIED",
  "message": "You do not have the required permission for this action",
  "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Troubleshooting

Symptom	Likely cause	What to do
401, or the handshake doesn’t even complete	Your key doesn’t exist, was miscopied, or was revoked — the server rejects the connection before listing any tool	Generate a new key (guide API keys) and update your client’s configuration block
You only see aymar_status in the tools list, nothing else	Your tenant isn’t on a Pro/Enterprise plan (aymar_status responds eligible: false), or your key has no read scope at all	Call aymar_status to confirm which of the two it is — check Plans and limits or your key’s “Customize” scope selection
One specific tool returns 403 PERMISSION_DENIED	Your key doesn’t have the exact scope that tool requires (see the “Required permission” column in the catalog)	Create a new key with that scope — an existing key’s scope selection can’t be widened, only revoked and recreated
404 reading or updating a specific id	The id doesn’t exist, or belongs to a different account — same response either way, by design	Confirm the id in the Platform; a 404 never means “it exists but you can’t access it”, it means “it isn’t there”
409 WHATSAPP_SESSION_WINDOW_CLOSED sending a message	The contact is on WhatsApp and more than 24h passed since their last inbound message	Use aymar_conversations_start with an approved template instead of aymar_conversations_send_message
422 VALIDATION_ERROR	The argument you gave the tool doesn’t match its schema (type, required field…)	The error’s own message/details describes the exact field — the tool validates the OpenAPI schema before calling the API
429 RATE_LIMIT_EXCEEDED	You went over your key’s per-minute or per-day request quota	Wait the seconds the error’s Retry-After gives you — see the per-plan ceilings in Plans and limits
A write tool does nothing, only returns a summary	You’re seeing confirmation_required — that’s expected behavior, not a failure	See The confirmation gate on writes
The MCP server doesn’t respond at all	The MCP server, or the public API behind it, is unavailable	The MCP server caches nothing: if the API doesn’t respond, the tool call fails too — retry later, or write to soporte@aymaragents.com with the request_id if you have one

Still stuck? Write to soporte@aymaragents.com with the tool name, the error’s request_id (if any) and a short description — never include your full API key in the message.