Rate Limits

Tools.FAST rate limits protect the platform and ensure fair usage for all users. Limits are applied per IP address and vary by endpoint type.

API rate limits

Tier-based concurrency limits

Rather than a simple requests-per-minute cap, the Tools.FAST API enforces concurrency and queue depth limits per tier:

If you exceed the queue limit, the API returns 429 with queue.limit_exceeded. If the worker pool is full, you receive queue.pool_saturated.

Response headers

When rate limited, the API returns 429 Too Many Requests with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "detail": "Too many requests. Retry after 12 seconds."
}

Queue limit responses

When your job queue is full:

{
  "error": "queue.limit_exceeded",
  "detail": "Too many queued jobs. Wait for existing jobs to complete."
}

When the worker pool is at capacity:

{
  "error": "queue.pool_saturated",
  "detail": "Worker pool is at capacity. Try again shortly."
}

Best practices

Respect Retry-After

Always check the Retry-After header on 429 responses and wait the specified number of seconds before retrying:

RESPONSE=$(curl -sS -w "\n%{http_code}" -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.heic" \
  -F "targetFormat=jpg" \
  -D /tmp/headers.txt)

HTTP_CODE=$(echo "$RESPONSE" | tail -1)

if [ "$HTTP_CODE" = "429" ]; then
  RETRY_AFTER=$(grep -i 'retry-after' /tmp/headers.txt | awk '{print $2}' | tr -d '\r')
  echo "Rate limited. Retrying in ${RETRY_AFTER}s..."
  sleep "$RETRY_AFTER"
  # ... retry the request
fi

try {
  $job = Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
    -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
    -Form @{ file = Get-Item "photo.heic"; targetFormat = "jpg" }
}
catch {
  if ($_.Exception.Response.StatusCode.value__ -eq 429) {
    $retryAfter = $_.Exception.Response.Headers.RetryAfter.Delta.TotalSeconds
    Write-Host "Rate limited. Retrying in ${retryAfter}s..."
    Start-Sleep -Seconds $retryAfter
    # ... retry the request
  }
}

Implement exponential backoff

For production integrations, use exponential backoff with jitter:

1. First retry: wait 1 second
2. Second retry: wait 2 seconds
3. Third retry: wait 4 seconds
4. Add random jitter (0-500ms) to each wait

Use polling intervals wisely

When polling job status, use reasonable intervals:

• 1-2 seconds for small files (images, short audio)
• 3-5 seconds for medium files (documents, long audio)
• 5-10 seconds for large files (video, bulk batches)

There is no rate limit on GET /job/{id}, but excessive polling wastes bandwidth without meaningful benefit.

Batch your submissions

Instead of submitting files one at a time, use batch endpoints where available. This reduces the number of HTTP requests and is more efficient for both your application and the API.

Monitor queue depth

Before submitting a large batch, check your entitlements to see remaining capacity:

curl -sS "https://api.tools.fast/convert/entitlements/me" \
  -H "X-Fast-Api-Key: $API_KEY" | jq

Invoke-RestMethod "https://api.tools.fast/convert/entitlements/me" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY }

This helps you avoid queue.limit_exceeded errors by knowing your current usage before submitting.

Identity provider rate limits

The accounts.tools.fast identity provider has its own rate limits for authentication endpoints:

These limits protect against brute-force attacks and are unlikely to affect normal API usage.