> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> API rate limits and best practices

All CloudCruise API endpoints are subject to the following global rate limits:

| Time Window | Max Requests |
| ----------- | ------------ |
| 1 second    | 500          |
| 15 seconds  | 1,000        |
| 60 seconds  | 2,000        |

Rate limits are tracked per API key (by workspace), and unauthenticated requests fall back to per-IP tracking. If multiple time windows are exceeded simultaneously, the most restrictive limit applies.

## 429 Response

When you exceed a rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too Many Requests",
  "limit": 500,
  "remaining": 0,
  "retryAfterSeconds": 1
}
```

| Field               | Description                                                                          |
| ------------------- | ------------------------------------------------------------------------------------ |
| `limit`             | Maximum requests allowed in the violated time window                                 |
| `remaining`         | Requests remaining in the violated window. This is `0` when the request is throttled |
| `retryAfterSeconds` | Seconds to wait before retrying                                                      |

The response also includes rate-limit headers: `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. Use `Retry-After` or `retryAfterSeconds` to decide when to retry.

## Best Practices

* **Use webhooks instead of polling.** [Webhooks](/concepts/webhooks) notify your server immediately when a run completes, eliminating the need for polling the [run results](/run-api/retrieve-run-results) endpoint.
* **Use our SDKs.** The [TypeScript](/sdk/js/overview) and [Python](/sdk/python/overview) SDKs use server-sent events for real-time updates, avoiding polling entirely.
* **Implement exponential backoff.** If you receive a `429`, wait for `retryAfterSeconds` before retrying and increase the delay on subsequent failures.