Rate Limits

Understand rate limits, monitor your usage, and implement proper retry logic to ensure reliable API access.

Overview

Rate limiting protects the API from abuse and ensures fair usage across all workspaces. All API requests are rate limited per workspace based on your subscription plan.

Rate limits are applied using a sliding window algorithm per minute. This means requests are counted within a rolling 60-second window, providing smooth and predictable rate limiting behavior.

Each plan tier has different rate limits to accommodate various usage patterns, from small projects to enterprise-scale operations.

Rate Limit Scope

Rate limits are applied per workspace, not per API key. All API keys within the same workspace share the same rate limit pool.

Rate Limit Headers

  • X-RateLimit-Limit - The maximum number of requests allowed per minute for your plan tier
  • X-RateLimit-Remaining - The number of requests remaining in the current window
  • X-RateLimit-Reset - Unix timestamp (in seconds) indicating when the current rate limit window resets

Every API response includes rate limit information in HTTP headers, allowing you to monitor your usage and implement intelligent retry logic. These headers are always present, even when the request is successful.

Use these headers to build rate limit-aware applications that can proactively manage their API usage.

Response Headers text 
// Example response headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1704067200

Implementation Tip

Monitor the X-RateLimit-Remaining header and implement exponential backoff when it approaches zero. This prevents hitting rate limits and ensures smooth API usage.

Handling Rate Limit Exceeded

When you exceed your rate limit, the API returns a 429 Too Many Requests status code. The response includes detailed information to help you implement proper retry logic.

The retryAfter field indicates the number of seconds you should wait before retrying the request. This value is calculated based on when the current rate limit window resets.

429 Response json 
{
  "error": {
    "en": "Rate limit exceeded",
    "ar": "تم تجاوز حد المعدل"
  },
  "retryAfter": 45
}

Best Practice

Always respect the retryAfter value and implement exponential backoff. Avoid aggressive retry loops that could further impact your rate limit. Consider implementing request queuing for high-volume scenarios.

Best Practices

  • Monitor rate limit headers in every response to track your usage
  • Implement exponential backoff when approaching rate limits
  • Use batch endpoints when available to reduce the number of requests
  • Cache responses when appropriate to minimize API calls
  • Consider upgrading your plan if you consistently approach rate limits
  • Implement request queuing for high-volume operations
  • Use webhooks for real-time updates instead of polling when possible

To maximize API reliability and avoid rate limit issues, follow these best practices: