Skip to main content
Version: Next

Retries

Copy for LLM

The Apify client automatically retries requests that fail due to:

  • Network errors
  • Internal errors in the Apify API (HTTP status codes 500 and above)
  • Rate limit errors (HTTP status code 429)

By default, the client retries a failed request up to 8 times. The retry intervals use an exponential backoff strategy:

  • The first retry occurs after 500 to 1,000 milliseconds.
  • The second retry occurs after 1,000 to 2,000 milliseconds, and so on.

The delay is spread over a random factor between one and two, so clients that failed together don't come back at the API in lockstep.

You can customize this behavior using the following options in the ApifyClient constructor:

  • maxRetries: Defines the maximum number of retry attempts.
  • minDelayBetweenRetriesMillis: Sets the minimum delay between retries in milliseconds.

Retries with exponential backoff help reduce the load on the server and increase the chances of a successful request.

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
    token: 'MY-APIFY-TOKEN',
    maxRetries: 8,
    minDelayBetweenRetriesMillis: 500,
});

When the retries are exhausted, the client throws the error of the final attempt. Which transport errors count as retryable is decided by the HTTP client the requests go through. The built-in axios client retries every network failure, timeouts included. A custom client classifies its own errors. For details, see HTTP clients.

A request that times out is retried the same way, with a longer timeout on each attempt. For how the timeouts are set, see Timeouts.

Wait for resources to start a run

Starting a run fails with an HTTP 402 error when the account doesn't have enough free memory for the run, or when it already runs as many Actors as its plan allows. The error type is actor-memory-limit-exceeded or concurrent-runs-limit-exceeded. The client doesn't retry these errors on its own, since they clear only after other runs or builds of the account finish.

To keep retrying the start until the resources free up, set the waitForResources option of ActorClient.start(), ActorClient.call(), or the same methods of TaskClient. The client then retries the start every 10 seconds, and the option value sets how long:

  • true retries until the run starts.
  • A number of seconds stops retrying after that time and throws the last error.

Any other error throws right away. A run that asks for more memory than the account's whole memory limit gets the same actor-memory-limit-exceeded error and never starts, so with true the client retries it forever. In call(), the time spent retrying doesn't count toward waitSecs.

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });

// Retry the start until the account has the resources for the run.
const run = await client.actor('username/actor-name').call(undefined, { waitForResources: true });

// Stop retrying after 10 minutes and throw the last error.
const startedRun = await client.task('username~task-name').start(undefined, { waitForResources: 600 });