Skip to content

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.


  1. Quota by Organization: Rate limits are calculated per organisation per 60-second sliding window based on the authenticated X-Organisation-Uuid.
  2. Tier-Based Limits: Your organization’s rate limit is determined by your active subscription plan.
  3. 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).


Every response from /developer/api/v1/* includes headers reflecting your current quota:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 120
X-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.

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
}
}
}

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.')
}

  • Cache Static Responses: Cache product catalogue and category listings locally to avoid redundant queries.
  • Use Webhooks for Event-Driven Sync: Instead of polling /orders or /inventory every 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.