Errors

There are two kinds of errors:

• Tool errors happen while a tool runs, for example when a quota is used up. They come back as a normal MCP tool result with isError: true, so the assistant can read them and react.
• HTTP errors happen before any tool runs, for example a missing or invalid credential.

Tool errors

The error text has the code in square brackets, a message the assistant can act on and, for some codes, JSON details:

Error executing tool search_leads: [quota_exceeded] Daily lead explore limit reached. It resets at 00:00 UTC. {"quota":{"used":2000,"limit":2000,"remaining":0,"resets_at":"2026-10-15T00:00:00+00:00"}}

Code	Meaning	What to do
invalid_argument	A parameter isn't valid. For example, the minimum salary is above the maximum, a cursor was reused with different filters, or the role to enrich has closed.	Fix the arguments. The message says what's wrong.
not_found	No lead or company has this id.	Use an id returned by a search.
not_entitled	Your plan doesn't include MCP access right now. The message gives the reason: no paid plan, a trial, an inactive subscription, or a plan without MCP.	Manage your plan. Credentials work again as soon as access is restored.
insufficient_scope	The credential lacks a scope the tool needs. In practice, leads:enrich for enrich_lead.	Create an API key with Allow enriching leads ticked, or reconnect the app and approve enrichment.
rate_limited	More than 60 tool calls in a minute. Details include retry_after_seconds.	Wait, then retry.
quota_exceeded	A daily quota is used up. Details include the quota.	Wait for the reset at 00:00 UTC. See Usage and limits.
insufficient_credits	No enrichment credits left this period. Details include credits.	Exploring stays free. Credits renew with your plan.
query_timeout	The query was too broad to finish in time.	Add filters such as location, title or posted_within_days.
unavailable	Estel data is temporarily unavailable.	Retry after a short wait.
internal_error	Something went wrong on our side. The message includes a reference id.	Retry. If it keeps happening, send the reference to support@estel.tech.

Error messages never include stack traces, SQL or internal names. Unexpected failures are logged on our side under the reference id.

HTTP errors

Status	When	What to do
401 Unauthorized	No credential, or the token or key is invalid, expired or revoked. The WWW-Authenticate header points to the protected resource metadata, which MCP clients use to start sign-in.	Sign in again, or check the API key.
429 Too Many Requests	Too many requests or failed sign-in attempts from your IP address.	Wait for the time in Retry-After.
413 Payload Too Large	The request body is larger than 1 MB.	Send smaller requests.
421 Misdirected Request	The Host header isn't mcp.estel.tech.	Connect to https://mcp.estel.tech/mcp directly.
403 Forbidden	The request came from a web page on an origin that isn't allowed. This protects against DNS rebinding.	Call the server from your app or backend, not from a browser page.

A 401 example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token or API key is invalid, expired or revoked", resource_metadata="https://mcp.estel.tech/.well-known/oauth-protected-resource/mcp"