Error codes

Aurora MCP returns errors as standard MCP tool errors. Most MCP clients will surface the message to you and usually retry once.

HTTP-level errors (from the gateway)

These are produced by the Envoy gateway before a tool ever runs.

Status	Meaning	What to do
401	Missing or invalid access token	Re-authorise the connector in your client. Usually means the token expired.
403	Token valid but scope insufficient	Contact Consilio support — your user is missing a required scope.
429	Rate limit	Retry after the `Retry-After` header value. The client will back off automatically.
503	Upstream Consilio API unavailable	Transient. Retry after a minute.

Tool-level errors (from the MCP server)

These are produced by the MCP server itself.

Code	When	Recovery
`INVALID_ALPHA_CODE`	`alpha_code` argument doesn’t match `^[A-Z]\d{5,6}$`.	Correct the matter code. `A12345`, not `a-12345`.
`MATTER_NOT_FOUND`	No matter matches the alpha-code for this user.	Confirm the matter exists in your portal access.
`WORKSPACE_AMBIGUOUS`	`searchDocuments` called without `workspace_id` on a multi-ws matter.	Retry with an explicit `workspace_id`. The error payload lists options.
`UPSTREAM_TIMEOUT`	Consilio API took longer than the per-request deadline.	Narrow the query (more specific terms, smaller matter).
`UPSTREAM_UNAVAILABLE`	Upstream API returned 5xx.	Retry. If persistent, email `support@consilio.com`.

What the client does automatically

Most MCP clients will retry once on transient errors (429, 503, UPSTREAM_TIMEOUT, UPSTREAM_UNAVAILABLE). On a second failure it will ask you what to do next rather than looping.

Reporting an error

If an error persists, email support@consilio.com with the subject line “MCP error” and include:

The approximate timestamp (UTC is fine).
The MCP client you were using.
The request-id from the error message, if present.