Rate Limiting

The Arsel API enforces per-organization rate limits to ensure fair usage and platform stability. Limits are applied per second across all API keys belonging to the same organization.

Default Limits

The API allows 2 requests per second per organization. This limit applies across all API keys belonging to the same organization.

If you need a higher rate limit, contact support@arsel.sa to discuss your requirements.

Rate Limit Headers

Every API response includes standard rate limit headers:

Header	Description
ratelimit-limit	Maximum requests allowed in the current window
ratelimit-remaining	Requests remaining in the current window
ratelimit-reset	Unix timestamp when the window resets

When a rate limit is exceeded, an additional header is included:

Header	Description
retry-after	Seconds to wait before retrying

Rate Limit Exceeded

If you exceed the limit, the API returns HTTP 429:

{
  "status_code": 429,
  "name": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after the period indicated in the retry-after header."
}

Handling Rate Limits

Read the headers. Check ratelimit-remaining before sending additional requests.

Implement exponential backoff. When you receive a 429, wait for the duration specified in retry-after before retrying. Avoid tight retry loops.

Spread requests over time. If you need to send a batch of messages, space them out rather than sending them all at once.

Example retry logic:

async function sendWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response;

    const retryAfter = response.headers.get("retry-after") || "1";
    await new Promise((resolve) =>
      setTimeout(resolve, parseInt(retryAfter) * 1000)
    );
  }
  throw new Error("Rate limit exceeded after maximum retries");
}