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](/en/api/errors/)** and **[Plans and limits](/en/api/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:

```json
{
  "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](/en/guides/claves-api/)**) 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](/en/api/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](/en/mcp/tools/)) | 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](/en/api/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](/en/mcp/confirm/)** |
| 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.