Rate limits

Certain mutations are subject to per-event rate limiting. Rate limits protect the platform from abuse and ensure fair usage across integrations.

How rate limits work

Mutations annotated with the @event directive are rate-limited based on configuration stored per event type. Limits are enforced per:

• Authenticated user — when the request is associated with a user account.
• IP address — when no user context is available.

When a rate limit is exceeded, the API returns:

{
  "errors": [
    {
      "message": "rate limit exceeded for event: CREATE_API_KEY",
      "extensions": {
        "Code": "EVENT_RATE_LIMIT_EXCEEDED",
        "Expected": true
      }
    }
  ]
}

Which operations are rate-limited?

Any mutation marked with @event(type: ...) in the schema is subject to rate limiting. The specific limits (max calls per time window) are configured per event type on the server side.

Check the API Reference — rate-limited mutations are listed under Mutations and include audit-log annotations in their descriptions.

Handling rate limits

1. Respect the error — do not immediately retry when you receive EVENT_RATE_LIMIT_EXCEEDED.
2. Implement exponential backoff — wait before retrying, starting at a few seconds and increasing.
3. Use idempotency keys — when you do retry a mutation, include the same Idempotency-Key header to avoid duplicate execution.
4. Batch where possible — avoid rapid-fire individual mutations when a single operation would suffice.

Idempotency and rate limits

Idempotency keys and rate limits work together:

• A new idempotency key on a rate-limited mutation will be rejected if the rate limit window has not elapsed.
• The same idempotency key on a previously completed mutation returns the cached result without counting against the rate limit.

Query rate limits

Read queries (non-mutation operations) are not subject to per-event rate limiting. However, the API enforces a query complexity limit (maximum complexity score of 500 per request). Very deep or wide queries may be rejected.

Contact us

If your integration requires higher rate limits, contact your account manager to discuss adjusted limits for your API key.