Rate Limiting

Queuety supports per-handler rate limiting to prevent overloading external APIs or other constrained resources. When a handler exceeds its rate limit, jobs are delayed until the window resets.

Setting a rate limit

Apply a rate limit when dispatching a job:

use Queuety\Queuety;

Queuety::dispatch( 'call_openai', $payload )
    ->rate_limit( 10, 60 ); // max 10 executions per 60 seconds

The two arguments are:

1. $max - Maximum number of executions allowed in the window
2. $window - Window duration in seconds

Handler-level rate limits

Set rate limits in the handler's config() method so they apply to every dispatch:

use Queuety\Handler;

class CallOpenAIHandler implements Handler {
    public function handle( array $payload ): void {
        // Call the API...
    }

    public function config(): array {
        return [
            'rate_limit' => [ 60, 60 ], // 60 requests per minute
        ];
    }
}

How it works

Rate limits are tracked per handler name. The worker checks the rate limiter before executing each job. If the handler has exceeded its limit within the current window, the job is released back to the queue with a delay until the window resets.

The rate limiter uses the queuety_logs table to count recent executions within the sliding window. This means rate limits are enforced across all worker processes, not just within a single worker.

Programmatic access

Access the rate limiter directly:

$limiter = Queuety::rate_limiter();

// Register a rate limit
$limiter->register( 'call_openai', 60, 60 );

// Check if a handler is rate limited
$allowed = $limiter->is_allowed( 'call_openai' );

Use cases

• External API limits. Match your rate limit to the API's quota (e.g., OpenAI's 60 RPM).
• Email throttling. Prevent sending too many emails in a short window.
• Resource protection. Limit CPU-intensive handlers to prevent starving other jobs.