Rate Limits - Blue API

The Blue API enforces rate limits on all API and personal access token (PAT) requests to ensure fair usage and platform stability. Limits are applied per second using a sliding window and vary by tier. Adding the Pro add-on doubles your tier’s limits.

Rate Limits by Tier

All limits are requests per second, across three layers. Each layer is checked independently — every request must pass all three to succeed.

Tier	Per API key	Per user	Per org
Starter	20 req/s	40 req/s	60 req/s
Starter+	30 req/s	60 req/s	90 req/s
Growth	50 req/s	100 req/s	150 req/s
Growth+	100 req/s	200 req/s	300 req/s
Scale	200 req/s	400 req/s	600 req/s
With Pro	2× tier	2× tier	2× tier
Enterprise	1,000 req/s	2,000 req/s	3,000 req/s

How It Works

Rate limits are checked in three layers for each request:

Per API key — limits individual token usage, preventing a single integration from consuming all capacity
Per user — limits total usage across all of a user’s tokens, preventing key rotation bypass
Per org — a hard ceiling on all API activity within an organization

All three layers must pass for a request to succeed. If any layer is exceeded, the request is rejected with a 429 status code.

Response Headers

Every API response includes rate limit headers based on the tightest (closest to limit) layer:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets
`Retry-After`	Seconds to wait before retrying (only on `429` responses)

Error Response

When a rate limit is exceeded, you’ll receive a 429 Too Many Requests response:

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

Operation-Specific Limits

Certain sensitive operations have additional per-operation limits, independent of the global limits above:

Operation	Rate Limit	Window
`signIn`	5 requests	60 seconds
`signInRequest`	3 requests	120 seconds
`createDocument`	5 requests	60 seconds
`sendTestEmail`	5 requests	60 seconds
`submitForm`	5 requests	60 seconds
`exportTodos`	1 request	50 seconds
`deleteCompany`	3 requests	60 seconds
`updateEmail`	3 requests	60 seconds
`verifyAcceptInvitation`	3 requests	60 seconds
`verifySecurityCode`	3 requests	60 seconds

Best Practices

Check response headers — monitor X-RateLimit-Remaining to anticipate limits before hitting them
Respect Retry-After — when you receive a 429, wait the specified number of seconds before retrying
Use a single API key per integration — avoid spreading requests across multiple keys to work around per-key limits, as user and org limits still apply
Batch where possible — use Blue’s GraphQL API to fetch multiple resources in a single request
Add Pro for 2× headroom — the Pro add-on doubles all three rate limit layers on any tier

For questions about rate limits or to discuss Enterprise limits, please contact our support team.