Rate Limits & Errors

Understand rate limits by plan tier and how to handle API errors gracefully.

Rate Limits by Plan

Rate limits are applied per organization and depend on your subscription tier. Limits use a token bucket algorithm with burst allowances.

Plan	Requests/min	Requests/hour	Burst Allowance
Free	10	100	20
Starter	30	1,000	50
Growth	100	5,000	200
Pro	300	20,000	500
Enterprise	1,000	100,000	2,000

Burst allowance lets you temporarily exceed per-minute limits for short bursts. Tokens refill continuously at your per-minute rate. The hourly limit acts as a hard cap.

Rate Limit Headers

Every API response includes rate limit headers so you can track your usage in real time.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute for your tier
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the rate limit window resets
`Retry-After`	Seconds to wait before retrying (only present on 429 responses)

Example response headers

HTTP/1.1 200 OK
Content-Type: application/json
Brighten-Version: 2026-01-01
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1707235260

Error Types

All errors follow a consistent format with a type, code, and human-readable message.

Error response format

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameter",
    "message": "recipient_id is required",
    "param": "recipient_id",
    "doc_url": "https://hellobrighten.com/developers/rate-limits"
  }
}

Type	Status	Description
`api_error`	500	An unexpected internal error occurred. Contact support if it persists.
`authentication_error`	401	Missing or invalid API key or OAuth2 token.
`authorization_error`	403	Valid credentials but insufficient permissions or scopes.
`invalid_request_error`	400	The request was malformed or missing required parameters.
`rate_limit_error`	429	Too many requests. Back off and retry after the Retry-After period.
`resource_not_found`	404	The requested resource does not exist or is not accessible.
`validation_error`	422	Request body failed validation. Check the param field for details.

Best Practices

1
Check X-RateLimit-Remaining before making requests to avoid hitting limits.
2
When you receive a 429, wait for the Retry-After seconds before retrying.
3
Implement exponential backoff for retries. Do not retry immediately on failure.
4
Cache responses where possible to reduce the number of API calls.
5
Use webhooks instead of polling for real-time updates.

Need higher limits?

Upgrade your plan or contact us for enterprise custom limits.

View Pricing