Errors & limits
What can go wrong, and the boundaries to design around.
Errors
401Unauthorized
Missing, malformed, expired, or revoked token. Check the Authorization header; generate a fresh token if needed.
429Too many requests
A token can make 600 MCP requests a minute. Wait for the number of seconds in the Retry-After header, then retry.
404Not found
The endpoint URL is wrong. It must be exactly https://mcp.lemon.domains/mcp.
tool error (validation)“MCP error -32602: Input validation error: …”
A parameter failed the tool's input schema (wrong type, bad format, out of range, or too long). The text names the field and the rule, e.g. expiryDate must match YYYY-MM-DD. Fix the argument and retry.
tool error (validation)“MCP error -32602: Tool … not found”
The tool name is misspelled or not one this server offers. Call tools/list, or check the tool reference.
tool error“Invalid date; use a real calendar date in YYYY-MM-DD format”
expiryDate matched the format but is not a real calendar date (e.g. 2027-13-45). Pass a valid date.
tool error“Invalid domain name format”
domainName is not a valid domain (e.g. it contains a space or has no TLD). Pass a bare name like example.com, without a scheme or path.
tool error“Project not found or you don't have access to it”
The projectId does not exist, or you are not a member of that project. Call list_projects to see your projects and roles.
tool error“You do not have edit access to this project”
You are a viewer on this project and the tool writes to it. Ask the project owner for editor access.
tool error“Only the project owner can perform this action”
The tool is owner-only (e.g. delete_project) and you are an editor or viewer. Ask the project owner to do it.
tool error“Domain not found”
No domain with that id or name exists in a project you belong to. Call list_domains to find the right id.
tool error“Provide either id or domainName”
get_domain was called with neither. Pass one of them. If you pass both, both must match the same domain.
tool error“Registrar not found”
The registrarId does not exist or belongs to someone else. Call list_registrars to see yours.
tool error“Registrar account not found”
The registrarAccountId does not exist or belongs to someone else. Call list_registrar_accounts to see yours.
tool error“This domain already exists in this registrar account”
Domain names are unique per registrar account. Use update_domain, or choose a different account.
tool error“That record already exists.”
The write would create a duplicate of a record that must be unique. Look up the existing record and update it instead of adding a new one.
tool error“Could not complete the request…”
A database-level error the server could not attribute to your input. The raw query is never exposed. Retry; if it persists, contact support.
How errors are returned
Authentication problems are HTTP errors (401). Everything that happens inside a tool call, including bad arguments and unknown tool names, comes back as a normal tool result flagged isError: true, not as a JSON-RPC error object. Your assistant reads the text and can react.
- Input validation errors. If an argument fails the tool's input schema, the handler never runs and the text starts with
MCP error -32602: Input validation error:followed by the field and the rule it broke. Fix the argument and retry. - Business-rule and not-found errors. The text starts with
Error:followed by one of the messages above, e.g.Error: Domain not found.
Database-level errors are always masked behind a neutral message; the server never returns a raw SQL query or your input values.
Limits
- Transport. Streamable HTTP only; the legacy SSE transport is disabled.
- Batch size.
bulk_add_domainsaccepts up to 200 domains per call. - Rate limit. 600 MCP requests a minute per token, counted separately from the REST API's limit.
- Request timeout. Individual requests run for up to 60 seconds.
- Scopes. Personal access tokens are either read-only or read + write, chosen when you create them. A read-only token gets "This token is read-only" from any tool that adds, changes or deletes data. OAuth connections have read + write access.
Need something the tools don't cover yet? Let us know. The surface is growing.