Concurrency & Priority

Control how many requests run in parallel, which run first, and what blocks lower-priority work until critical requests resolve.

Setting concurrency limits

import { createRetryer } from 'axios-retryer';

const retryer = createRetryer({
  maxConcurrentRequests: 6,   // At most 6 requests run simultaneously
  queueDelay: 50,             // 50ms between dequeue ticks (0 for max throughput)
  maxQueueSize: 200,          // Reject with QueueFullError if queue exceeds 200
});

Request priorities

Every request in the queue is sorted by priority. CRITICAL requests always dequeue before MEDIUM or LOW work:

import { AXIOS_RETRYER_REQUEST_PRIORITIES } from 'axios-retryer';

// CRITICAL: auth, checkout, user-initiated actions
retryer.axiosInstance.post('/auth/login', creds, {
  __axiosRetryer: { priority: AXIOS_RETRYER_REQUEST_PRIORITIES.CRITICAL },
});

// HIGH: primary page content
retryer.axiosInstance.get('/api/dashboard', {
  __axiosRetryer: { priority: AXIOS_RETRYER_REQUEST_PRIORITIES.HIGH },
});

// MEDIUM: secondary data (default when omitted)
retryer.axiosInstance.get('/api/sidebar');

// LOW: background prefetch, analytics events
retryer.axiosInstance.post('/api/analytics', event, {
  __axiosRetryer: { priority: AXIOS_RETRYER_REQUEST_PRIORITIES.LOW },
});

Blocking high-priority work

Set blockingPriorityThreshold to hold all lower-priority requests in the queue until all blocking requests resolve:

import { createRetryer, AXIOS_RETRYER_REQUEST_PRIORITIES } from 'axios-retryer';

const retryer = createRetryer({
  blockingPriorityThreshold: AXIOS_RETRYER_REQUEST_PRIORITIES.CRITICAL,
  cancelPendingOnDependencyFailure: true,  // Abort queued LOW/MEDIUM if CRITICAL fails
});

Handling queue overflow

import { QueueFullError } from 'axios-retryer';

try {
  await retryer.axiosInstance.get('/api/resource');
} catch (err) {
  if (err instanceof QueueFullError) {
    // Apply backpressure — don't alert Sentry for this
    showToast('System is busy. Please wait a moment.');
    return;
  }
  throw err;
}

High-throughput backend services

For Node.js workers calling a rate-limited API, tune concurrency to match the upstream rate limit:

// Third-party API allows 20 req/s
const externalApi = createRetryer({
  maxConcurrentRequests: 20,
  queueDelay: 0,            // No artificial pacing — let the concurrency cap do the work
  maxQueueSize: 1000,
  retries: 3,
});

// Bulk operation: fan out across the queue, respect concurrency
async function processItems(items: string[]) {
  return Promise.allSettled(
    items.map(id => externalApi.axiosInstance.get(`/items/${id}`))
  );
  // Up to 20 run concurrently; the rest queue automatically
}

Priority under contention

With 3 concurrent slots, multiple priorities in flight, and a slow API:

const retryer = createRetryer({ maxConcurrentRequests: 3 });

// Fire 10 requests of mixed priority simultaneously
const requests = [
  ...Array(4).fill(null).map(() =>
    retryer.axiosInstance.get('/api/data', {
      __axiosRetryer: { priority: AXIOS_RETRYER_REQUEST_PRIORITIES.LOW },
    })
  ),
  ...Array(3).fill(null).map(() =>
    retryer.axiosInstance.get('/api/data', {
      __axiosRetryer: { priority: AXIOS_RETRYER_REQUEST_PRIORITIES.HIGH },
    })
  ),
  retryer.axiosInstance.get('/api/critical', {
    __axiosRetryer: { priority: AXIOS_RETRYER_REQUEST_PRIORITIES.CRITICAL },
  }),
];
// HIGH and CRITICAL complete well before LOW in the queue
await Promise.allSettled(requests);

Migration Guide → Configuration reference →