Rate Limits & Tier Quotas
To ensure high availability and prevent traffic spikes from degrading service for other merchants, the Akoole Developer Platform enforces rate limits on all incoming requests.
How Rate Limits Work
Section titled “How Rate Limits Work”- Quota by Organization: Rate limits are calculated per organisation per 60-second sliding window based on the authenticated
X-Organisation-Uuid. - Tier-Based Limits: Your organization’s rate limit is determined by your active subscription plan.
- Graceful Fallback: If a plan does not specify a custom rate limit, a default threshold of 120 requests per minute is automatically enforced.
| Subscription Plan | Default Rate Limit | Max Webhook Endpoints |
|---|---|---|
| Starter | Public API disabled | Disabled |
| Growth / Standard | 120 req / min | 5 endpoints |
| Enterprise / Custom | 300 - 1,000+ req / min | Unlimited |
(Merchants requiring higher throughput can request a custom plan limit via Akoole Support).
Rate Limit Response Headers
Section titled “Rate Limit Response Headers”Every response from /developer/api/v1/* includes headers reflecting your current quota:
HTTP/1.1 200 OKContent-Type: application/jsonX-RateLimit-Limit: 120X-RateLimit-Remaining: 118| Header | Description |
|---|---|
X-RateLimit-Limit |
Maximum number of requests allowed within the current 60-second window. |
X-RateLimit-Remaining |
Number of requests remaining in the current window. |
Retry-After |
Included when rate limited (429). The number of seconds to wait before retrying. |
Handling 429 Too Many Requests
Section titled “Handling 429 Too Many Requests”When your organization exceeds its limit within a window, the API returns HTTP status 429 Too Many Requests with a JSON payload:
{ "status": "error", "error": { "code": "too_many_requests", "message": "Too many requests. Please slow down and respect your plan rate limits.", "details": { "retry_after_seconds": 24 } }}Recommended Retry Strategy
Section titled “Recommended Retry Strategy”When building clients, always implement exponential backoff with jitter when encountering a 429:
async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3): Promise<Response> { for (let attempt = 0; attempt <= maxRetries; attempt++) { const res = await fetch(url, options)
if (res.status === 429) { const retryAfter = Number(res.headers.get('Retry-After')) || Math.pow(2, attempt) // Add random jitter (0-500ms) to prevent thundering herd const delay = retryAfter * 1000 + Math.random() * 500 await new Promise((r) => setTimeout(r, delay)) continue }
return res } throw new Error('Rate limit exceeded after maximum retries.')}Best Practices
Section titled “Best Practices”- Cache Static Responses: Cache product catalogue and category listings locally to avoid redundant queries.
- Use Webhooks for Event-Driven Sync: Instead of polling
/ordersor/inventoryevery 5 seconds, register an Outbound Webhook to receive real-time push updates. - Batch Processing: Use pagination limits (
?limit=50) rather than querying item-by-item in tight loops.