Skip to main content

​
Rate limits

The MCP endpoint sits behind a per-Space throttle, shared across all MCP clients connected to that Space.
LimitValue
Requests per Space per minute60
That’s enough headroom for typical Ask-AI-style flows where each user message triggers one to a handful of tool calls. If you’re driving the MCP server from an automated agent that fans out across many tool calls per turn, you may hit the limit during a heavy iteration. Limits are returned in standard response headers: 
X-RateLimit-Limit:     60
X-RateLimit-Remaining: 42
X-RateLimit-Reset:     1734567890
When you exceed the limit you get a 429 Too Many Requests JSON-RPC error and a Retry-After header. MCP-aware clients (Claude Desktop, Cursor) back off automatically on 429 and retry once the window clears.

​
Underlying API limits

Each MCP tool delegates to a Public API V1 endpoint, and those endpoints have their own per-Space throttles:
ToolUnderlying endpoint limit
list_events, get_event7/minute
list_contacts, get_contact15/minute
list_companies, get_company15/minute
query_ad_metrics30/minute
The MCP endpoint throttle (60/minute) is hit first in most cases, but a chatty single tool can still trip its own per-endpoint limit before the MCP throttle catches it.

​
Error envelope

Every error from an MCP tool returns a structured envelope so the model can recover deterministically without parsing prose: 
[<error_class>] <human-readable message>
Reference ID: <correlation_id>
The [error_class] prefix is one of:
ClassWhen it firesWhat the model should do
validation_errorBad parameter shape, enum, or type.Re-call with corrected args (e.g. valid date format, supported operator).
authorization_errorToken doesn’t grant the requested scope, or user lost Space access.Stop. Surface “I lost access to this Space” to the user.
not_foundRecord (event/contact/company by ID) doesn’t exist.Surface “no record with that ID” to the user. Don’t retry.
rate_limitedPer-Space or per-endpoint throttle hit.Wait, back off, then retry.
upstream_unavailableSingleStore or an ad-platform API is temporarily down.Retry once after a short wait.
internal_errorUnhandled exception. Already logged to Sentry with the correlation_id.Stop. Surface “something went wrong” to the user.
unknown_toolTool name doesn’t exist on this server.Drop the call; the model probably hallucinated the tool.
The Reference ID: … is the row ID in mcp_audit_log for this call. Include it in support requests so the Cometly team can trace the failure end-to-end.

​
Validation error detail

Validation errors include the field-by-field reasons, formatted for the model: 
[validation_error] The given data was invalid.
- custom_field_filters.0.field: The custom field profile_field_19 is not configured for this space. Configure a label in the Cometly dashboard before filtering by it.
- custom_field_filters.0.operator: The operator "greater_than" is not supported for text fields. Allowed: equal_to, not_equal_to, contains, not_contains, starts_with, ends_with, contains_word, any, unknown.
Reference ID: 5a8d1e29-...
Validation errors are not reported to Sentry — they’re user-input failures. Other 5xx-mapped failures are.

​
Best practices for client builders

  1. Always parse the [error_class] prefix, not the message text. Messages may evolve; the class won’t.
  2. Honour Retry-After on 429. Cometly doesn’t bill for retries, but a hot loop will keep you locked out.
  3. Surface the Reference ID to end users when an error escapes. It’s the fastest way to get a real diagnosis from support.
  4. Don’t cache 401 responses. When OAuth tokens expire, the next call has to walk the flow.