Skip to main content

​
Overview

The Partner API enforces per-partner rate limiting using a sliding window algorithm. Each API Key has an independent rate limit counter.
Rate limiting is only active when a rateLimit value has been configured for your API Key. If no limit is configured, requests are not throttled. Contact the CleanLife integration team to confirm your rate limit quota.

​
How It Works

  1. Every authenticated request counts toward your API Key’s limit within the current window.
  2. The window is 60 seconds (sliding). When a new window starts, the counter resets.
  3. If the counter exceeds your configured limit, the request is rejected with 429 Too Many Requests.

​
Rate Limit Window

PropertyValue
Window typeSliding window
Window duration60 seconds
Counter scopePer API Key (not per IP, not per endpoint)

​
Rate Limit Error

When the limit is exceeded, the API returns: HTTP Status: 429 Too Many Requests 
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Partner API rate limit exceeded",
    "requestId": "a1b2c3d4-..."
  }
}
The Retry-After header is not currently included in the 429 response. The window is always 60 seconds, so you can safely wait 60 seconds before retrying.

​
Retry Behavior

When you receive a 429, implement the following retry strategy:
  1. Stop sending requests immediately — do not retry in a tight loop.
  2. Wait at least 60 seconds — the full sliding window duration.
  3. Resume with reduced throughput — spread requests evenly rather than bursting.
attempt 1: wait 60s
attempt 2: wait 90s
attempt 3: wait 120s

​
Best Practices

​
Spread Your Requests

Avoid sending all requests in a burst at the start of each minute. Spread them evenly across the 60-second window. Bad: 
Second 0:  50 requests → hits limit
Seconds 1–59: requests rejected
Good: 
Evenly distribute: ~1 request/second for a 60 req/min limit

​
Use a Queue

For high-volume operations (e.g. batch booking creation), use an internal queue in your system that dispatches requests at a controlled rate rather than sending them all simultaneously.

​
Handle 429 Gracefully

Always check for the 429 status code in your HTTP response handling. Do not treat it as a fatal error — it is recoverable. 
async function callWithRetry(fn, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.response?.status === 429 && attempt < maxAttempts) {
        const waitMs = 60_000 * attempt; // 60s, 120s, 180s
        console.warn(`Rate limited. Waiting ${waitMs}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, waitMs));
        continue;
      }
      throw err;
    }
  }
}

​
Monitor Usage

Log every 429 response your integration receives. A sustained rate of 429 errors indicates that your request throughput is too high. Consider requesting a higher limit from the CleanLife team.

​
Requesting a Higher Limit

If your integration requires a higher throughput, contact the CleanLife integration team with:
  • Your partner ID
  • Your expected peak requests per minute
  • A brief description of your use case
Rate limits are configured per API Key and can be adjusted on a case-by-case basis.