Skip to main content

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.

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.
HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed in the current window.
X-RateLimit-RemainingRequests remaining before you hit the limit. Never negative.
X-RateLimit-ResetUnix epoch (seconds) when capacity is expected to become available again.
X-RateLimit-WindowThe window the headers describe: minute, hour, or day.
Retry-AfterPresent only on 429 responses. Number of seconds to wait before retrying.
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.

​
429 response

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

1

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.
2

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.
3

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.
4

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.

​
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

Limits are configured at the OAuth client level. Contact your account manager to view or adjust the limits for your integration.
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.
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.
Yes. Contact your account manager with details about your use case and expected volume. We can adjust limits for high-volume integrations.