Rate Limits

The Blue API rate-limits every request authenticated with a personal access token (PAT) or session JWT. Limits protect platform stability and keep one integration from starving the rest of an organization. Limits are applied per minute using a 60-second sliding window and scale with your organization’s tier. Adding the Pro add-on doubles your tier’s limits.

Limits by tier

Each request is checked against three layers (per key, per user, per organization). The numbers are requests per minute. The per-organization layer is the hard ceiling on all API activity in the org.

Legacy tiers (pre-2026 AppSumo and direct licenses) all resolve to 200/min per key, 400/min per user, 600/min per org.

Plan overlays

Plans (Pro, Enterprise) sit on top of whatever tier the organization is on and override its rate limits:

Pro doubles all three of the tier’s limits. Enterprise replaces them with fixed 1,000 / 2,000 / 3,000 per minute regardless of the underlying tier.

Default fallback

If an organization has no resolvable tier (for example, an unconfigured or locked org), requests fall back to 200/min per key, 400/min per user, and 600/min per org.

How it works

Every request runs through up to three layers before any resolver executes. All applicable layers must pass; if any one is exceeded, the request is rejected with 429 Too Many Requests.

1. Per API key — limits a single token’s usage so one integration can’t consume the whole org’s capacity. This layer applies only when both PAT headers (blue-token-id and blue-token-secret) are present. Requests authenticated with a session JWT (Authorization: Bearer) skip this layer.
2. Per user — limits total usage across all of a user’s tokens, so rotating keys can’t bypass the per-key limit.
3. Per organization — the hard ceiling on all API activity within the organization.

Response headers

The tier limiter sets the following headers, based on the tightest layer (the one closest to its limit):

Error response

When a tier limit is exceeded, you receive a 429 Too Many Requests response with this JSON body:

{
  "error": "RATE_LIMITED",
  "message": "Too many requests. Limit: 20 per minute.",
  "retryAfter": 12
}

retryAfter is the number of seconds until the oldest request in the window ages out, freeing a slot.

Per-operation limits

Some sensitive operations carry their own limit, independent of the tier limits above. These run inside GraphQL: exceeding one returns a normal HTTP 200 with a RATE_LIMITED error in the response’s errors array (no 429, no rate-limit headers). The limiter keys on the authenticated user, falling back to the client IP for unauthenticated calls.

createCommunityPost is additionally capped at 100 requests per hour across all users combined.

Best practices

• Use one API key per integration. Spreading requests across multiple keys to dodge the per-key limit doesn’t help — the per-user and per-org limits still apply.
• Watch X-RateLimit-Remaining. Slow down before you hit the limit rather than after.
• Respect Retry-After. On a 429, wait the specified number of seconds before retrying.
• Batch with GraphQL. Fetch multiple resources in a single request instead of many small ones — see Making Requests.
• Add Pro for 2× headroom. The Pro add-on doubles all three layers on any tier.

For Enterprise limits, contact support.

Related

• Making Requests
• Authentication
• Error Codes