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

# Rate limits

> Stay within your API quotas and handle rate-limit responses

The ApifyCloud API enforces rate limits on authenticated requests to protect
platform stability. When a request exceeds its quota, the API responds with
`429 Too Many Requests`.

## Response headers

API responses include headers describing your current rate-limit state. They
appear on all responses **except** `401` (invalid or missing authentication)
and `403` (insufficient permissions), which are evaluated before the rate
limiter.

| Header                  | Description                                                                 |
| ----------------------- | --------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The maximum number of requests allowed in the current window.               |
| `X-RateLimit-Remaining` | Requests remaining before you hit the limit. Never negative.                |
| `X-RateLimit-Reset`     | Unix epoch (seconds) when capacity is expected to become available again.   |
| `X-RateLimit-Window`    | The window the headers describe: `minute`, `hour`, or `day`.                |
| `Retry-After`           | Present only on `429` responses. Number of seconds to wait before retrying. |

<Note>
  The values can change between requests as quotas shift. **Read the headers
  on every response** instead of assuming a fixed window — that's the most
  reliable way to pace your traffic.
</Note>

## 429 response

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735689600
X-RateLimit-Window: minute
Retry-After: 23

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}
```

## Handling 429 responses

<Steps>
  <Step title="Honour Retry-After">
    Wait at least the number of seconds in `Retry-After` before retrying the
    same request. This value reflects when capacity is expected to be available.
  </Step>

  <Step title="Add jitter">
    If multiple processes share the same OAuth client, retrying at exactly the
    same time produces another burst. Add a small random delay (for example
    `Retry-After * (1 + random(0, 0.25))`) so retries are spread out.
  </Step>

  <Step title="Cap retry attempts">
    Don't retry indefinitely. Stop after 3–5 attempts and surface a clear error
    to the end user. If you've exhausted a long window (for example a daily
    quota), retrying won't help until that window resets.
  </Step>

  <Step title="Slow down proactively">
    The `X-RateLimit-Remaining` header lets you adapt before hitting the limit.
    A common rule: when `Remaining < Limit * 0.1`, insert small delays between
    requests to glide through the window without triggering 429.
  </Step>
</Steps>

## Best practices

* **Use a single OAuth client per integration.** Don't spin up a new client per
  user or per request. Quotas are per-client, so consolidating preserves
  capacity.
* **Cache where you can.** Endpoints that return slow-changing data (for
  example app metadata, template lists) are good candidates for caching at
  your end. Every cached read is a request you don't make.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What are the limits for my integration?">
    Limits are configured at the OAuth client level. Contact your account
    manager to view or adjust the limits for your integration.
  </Accordion>

  <Accordion title="Why did I get a 429 right after a successful request?">
    Quota state changes continuously. The headers on a previous `2xx` response
    are a snapshot, not a guarantee about subsequent calls. Always honour
    `Retry-After` on `429` and use the headers on the most recent response to
    plan your next request.
  </Accordion>

  <Accordion title="Do failed requests count toward my limit?">
    A request counts once it has been authenticated and authorized, regardless
    of the final status. This includes successful `2xx` responses, validation
    errors (`400`), server errors (`5xx`), and the request that triggers a
    `429`. Requests rejected with `401` (invalid or missing authentication) or
    `403` (insufficient permissions) are checked before the rate limit and do
    not count.
  </Accordion>

  <Accordion title="Can I request a higher quota?">
    Yes. Contact your account manager with details about your use case and
    expected volume. We can adjust limits for high-volume integrations.
  </Accordion>
</AccordionGroup>