# How auth0-deploy-cli Handles Auth0 API Rate Limiting: Retry Logic and Configuration

> auth0-deploy-cli handles Auth0 API rate limiting with configurable exponential backoff retries for 429 errors and Retry-After headers.

- Repository: [Auth0/auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli)
- Tags: internals
- Published: 2026-02-25

---

**Auth0-deploy-cli protects against Auth0 Management API throttling by wrapping every mutable API call in a configurable retry-with-exponential-backoff helper that detects 429 errors, honors Retry-After headers, and supports environment-based tuning.**

The auth0-deploy-cli is an open-source infrastructure-as-code tool that synchronizes Auth0 tenant configurations through the Management API. When deploying large configurations involving hundreds of clients, rules, or resource servers, the tool must gracefully handle Auth0 API rate limiting to ensure reliable, automated deployments without manual intervention.

## Central Retry Helper Implementation

The core rate-limiting protection lives in [`src/tools/auth0/handlers/default.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/default.ts), specifically within the `retryWithExponentialBackoff` function (lines 45-86). This utility wraps asynchronous API operations and implements a resilient backoff strategy.

### Detecting Rate Limit Conditions

The helper identifies rate-limiting scenarios by checking for HTTP 429 status codes or error messages containing "Too Many Requests" strings. When `error.statusCode === 429` is detected, the retry logic triggers immediately.

### Exponential Backoff with Jitter

The implementation calculates delays using an exponential growth formula (`initialDelay * 2ⁿ`) combined with random jitter (0-1 seconds) to prevent thundering-herd problems. The delay respects an upper bound defined by configuration, ensuring backoffs do not grow indefinitely.

### Respecting Retry-After Headers

When the Auth0 API returns a `Retry-After` response header, the helper overrides its calculated delay and waits exactly the duration specified by the server. This ensures compliance with Auth0's rate-limiting policy while minimizing unnecessary wait times.

## Configuration Options

The retry behavior is fully configurable through environment variables read at runtime:

| Variable | Purpose | Default |
|----------|---------|---------|
| **AUTH0_MAX_RETRIES** | Maximum retry attempts before failing | 3 |
| **AUTH0_RETRY_INITIAL_DELAY_MS** | Base delay in milliseconds before first retry | 1000 |
| **AUTH0_RETRY_MAX_DELAY_MS** | Upper bound for backoff delay in milliseconds | 30000 |

These values are assembled into a `retryConfig` object within `processChanges` (lines 91-99 of [`default.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/default.ts)) and passed to the retry helper.

To customize retry behavior for a large deployment, set the variables before running the CLI:

```bash
export AUTH0_MAX_RETRIES=5
export AUTH0_RETRY_INITIAL_DELAY_MS=2000
export AUTH0_RETRY_MAX_DELAY_MS=60000
node lib/index.js import -c config.json -i ./my-config/

```

## Integration in Resource Handlers

All CRUD operations leverage the retry logic through the `APIHandler.processChanges` method. The implementation uses the Auth0 client pool to queue tasks, wrapping each mutable operation with `retryWithExponentialBackoff`.

For example, delete operations follow this pattern:

```typescript
await this.client.pool
  .addEachTask({
    data: del,
    generator: delItem =>
      retryWithExponentialBackoff(() => {
        const delFn = this.getClientFN(this.functions.delete);
        return delFn(delItem[this.id]);
      }, retryConfig)
      .then(() => this.didDelete(delItem))
  })
  .promise();

```

This pattern ensures that creates, updates, and deletes across all resource types—including clients, rules, and connections—automatically benefit from rate-limit protection.

## Special Case: Non-Blocking Rate Limits

Not all handlers retry on 429 errors. The **Prompts** handler ([`src/tools/auth0/handlers/prompts.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/prompts.ts)) implements specialized logic where rate limits are treated as non-blocking errors. Instead of retrying, it logs the error and continues deployment:

```typescript
if (error && error.statusCode === 429) {
  log.error(
    `The global rate limit has been exceeded, resulting in a ${error.statusCode} error...`
  );
  return null;
}

```

This behavior (lines 33-38) reflects a design decision that prompt configuration failures should not halt entire deployment pipelines.

## Summary

- **Core Protection**: The `retryWithExponentialBackoff` function in [`src/tools/auth0/handlers/default.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/default.ts) provides centralized rate-limit handling for all mutable Auth0 API calls.
- **Smart Backoff**: Implements exponential delay with random jitter while honoring `Retry-After` headers to comply with server-side rate limiting.
- **Environment Control**: Configure retry limits and delays via `AUTH0_MAX_RETRIES`, `AUTH0_RETRY_INITIAL_DELAY_MS`, and `AUTH0_RETRY_MAX_DELAY_MS`.
- **Universal Coverage**: All resource handlers (clients, rules, connections) automatically use the retry logic through the `processChanges` pipeline.
- **Exception Handling**: The Prompts handler treats 429 errors as warnings rather than retryable failures, allowing deployments to continue.

## Frequently Asked Questions

### What happens when auth0-deploy-cli receives a 429 error from the Auth0 API?

When the tool detects a 429 status code or "Too Many Requests" message, it automatically initiates a retry sequence with exponential backoff. The delay doubles with each attempt (plus random jitter) until the operation succeeds or reaches the maximum retry count defined by `AUTH0_MAX_RETRIES`.

### How do I increase the number of retry attempts for large deployments?

Set the `AUTH0_MAX_RETRIES` environment variable before executing the CLI. The default value is 3, but you can increase it for environments with strict rate limits or large configuration sets. Combine this with adjusted `AUTH0_RETRY_INITIAL_DELAY_MS` values to fine-tune the aggression of your retry strategy.

### Does auth0-deploy-cli respect the Retry-After header sent by Auth0?

Yes. According to the source code in [`src/tools/auth0/handlers/default.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/default.ts), the helper checks for the `Retry-After` response header and uses its value to override the calculated exponential delay. This ensures the tool waits exactly as long as the Auth0 API requests, optimizing deployment speed while respecting limits.

### Are all API calls retried when rate limited?

No. While most resource handlers (clients, rules, connections) automatically retry on 429 errors, the Prompts handler ([`src/tools/auth0/handlers/prompts.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/prompts.ts)) treats rate limits as non-blocking errors. It logs the 429 error and continues with the deployment rather than retrying, based on the implementation at lines 33-38.