The SDK uses a two-layer approach to keep your requests within API limits:

| Layer | Type | How it works |

|---|---|---|

| **Native Throttling** | Proactive (client-side) | Sliding window rate limiter blocks outgoing requests *before* they hit the server |

| **429 Retry & Adaptive Polling** | Reactive (server-side) | Catches HTTP 429 responses, retries with backoff, and slows polling when limits are low |

The proactive layer prevents most 429 errors from ever occurring. The reactive layer acts as a safety net for edge cases (clock drift, concurrent processes, plan changes).

Every `SharpApiClient` instance includes an in-memory **sliding window rate limiter** (`SlidingWindowRateLimiter`) that tracks request timestamps in a 60-second rolling window.

Before each API call, `waitIfNeeded()` checks the window. If capacity is available the request proceeds immediately; if not, the call sleeps until the oldest timestamp expires out of the window.

- **Default limit:** 60 requests/minute (matches most subscription plans)

- **Per-process, in-memory** — no external dependencies (Redis, database, etc.)

- **Server-adaptive** — when the server returns a higher `X-RateLimit-Limit` header (e.g. after a plan upgrade), the limiter automatically ratchets up to match. It never ratchets *down*, so your configured default is always the floor.

- **Metadata bypass** — `ping()` and `quota()` skip throttling to avoid deadlocks when checking connectivity or subscription status.

$client = new SharpApiClient('your-api-key');

// Change the throttle limit (default: 60)

$client->setRequestsPerMinute(120);

// Disable throttling entirely (pass 0)

$client->setRequestsPerMinute(0);

You can access the underlying `SlidingWindowRateLimiter` instance directly for fine-grained control:

$limiter = $client->getRateLimiter();

// Non-blocking check — returns true if a request can proceed without waiting

$limiter->canProceed();

// How many requests are available in the current window

$limiter->remaining(); // e.g. 42

**Cross-process state caching** — save and restore the server-reported rate limit state (e.g. between HTTP requests in a web app):

// After an API call, cache the server-reported state

$state = $client->getRateLimitState();

// $state = ['limit' => 60, 'remaining' => 58]

cache()->put('sharpapi_rate_state', $state, 60);

// In the next process/request, restore it

$client->setRateLimitState(cache()->get('sharpapi_rate_state'));

**Quick quota check** — verify the server still reports available capacity before making a request:

if ($client->canMakeRequest()) {

// Server-reported remaining > 0 (or no server data yet)

}

If a request does hit the server rate limit, the SDK handles it automatically: