Rate limits
Hapana applies a leaky-bucket rate limit at the API gateway with two layers — your tier and the endpoint category. Both must allow the request.
Tier limits
Every API key belongs to a tier, set when the key is issued. The tier caps total requests per hour across all endpoints.
| Tier | Requests / hour | Audience |
|---|---|---|
| Free | 100 | Sandbox and trial integrations |
| Starter | 1,000 | Single-location operators |
| Professional | 10,000 | Multi-location brands; required for Member API |
| Enterprise | 100,000 | White-label partners and high-volume integrations |
Endpoint category limits
Independent of your tier, each endpoint category has its own per-hour cap. This protects expensive endpoints from being starved by cheap ones.
| Category | Requests / hour | Examples |
|---|---|---|
| Read | 1,000 | GET /clients, GET /sessions |
| Write | 200 | POST /bookings, PATCH /clients/{id} |
| Bulk | 10 | Anything matching /bulk, /batch, /import |
| Report | 5 | /reports, /analytics, /statistics |
| Content read / write | 1,000 / 200 | Content suite endpoints under /v2/content/* and /v2/member/content/* |
Member API
Authenticated Member API calls are rate-limited per member token at 100 requests per minute. The Member API requires Professional or Enterprise tier on the parent brand's API key.
Response headers
Every response includes the current bucket state. Cache these — don't recompute on every call.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Total requests allowed in the current window |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix epoch seconds when the window resets |
X-RateLimit-Category | Which endpoint category was applied (read, write, bulk, report, content_read, content_write) |
Retry-After | Seconds to wait before retrying — only present on 429 responses |
When you hit a limit
The API responds with HTTP 429 Too Many Requests and a Retry-After header. Back off, wait the indicated seconds, and retry. Don't retry tighter than Retry-After — successive immediate retries don't reset the bucket and may trigger a longer cooldown at the gateway.
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1745601234
X-RateLimit-Category: readRecommended client behaviour
- Read
X-RateLimit-Remainingon every response and slow down before you hit zero. - On a 429, sleep for
Retry-Afterseconds and retry once. If it 429s again, exponential backoff with jitter. - For bulk operations, prefer the dedicated bulk endpoints over loops of single-resource calls — they share a separate, smaller bucket but use far fewer tokens per logical operation.
- Webhook callbacks are not subject to rate limits — design event-driven workflows around webhooks rather than polling.