Rate Limits & Errors

Rate limits

The MCP endpoint sits behind a per-Space throttle, shared across all MCP clients connected to that Space.

Limit	Value
Requests per Space per minute	60

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:

Tool	Underlying endpoint limit
`list_events`, `get_event`	7/minute
`list_contacts`, `get_contact`	15/minute
`list_companies`, `get_company`	15/minute
`query_ad_metrics`	30/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:

Class	When it fires	What the model should do
`validation_error`	Bad parameter shape, enum, or type.	Re-call with corrected args (e.g. valid date format, supported operator).
`authorization_error`	Token doesn’t grant the requested scope, or user lost Space access.	Stop. Surface “I lost access to this Space” to the user.
`not_found`	Record (event/contact/company by ID) doesn’t exist.	Surface “no record with that ID” to the user. Don’t retry.
`rate_limited`	Per-Space or per-endpoint throttle hit.	Wait, back off, then retry.
`upstream_unavailable`	SingleStore or an ad-platform API is temporarily down.	Retry once after a short wait.
`internal_error`	Unhandled exception. Already logged to Sentry with the `correlation_id`.	Stop. Surface “something went wrong” to the user.
`unknown_tool`	Tool 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

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

Get Started

Connecting Clients

Tools

Resources

Prompts

Rate limits

Underlying API limits

Error envelope

Validation error detail

Best practices for client builders

​Rate limits

​Underlying API limits

​Error envelope

​Validation error detail

​Best practices for client builders

Rate limits

Underlying API limits

Error envelope

Validation error detail

Best practices for client builders