HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1743750060

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743750060
Retry-After: 23

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. You have sent 60 requests in the current minute. Please wait and retry."
}

delay = min(base * 2^attempt, cap) + random(0, jitter)

interface RetryOptions {
  maxRetries?: number;
  baseDelayMs?: number;
  capMs?: number;
  jitterMs?: number;
}
 
async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  options: RetryOptions = {},
): Promise<T> {
  const {
    maxRetries = 3,
    baseDelayMs = 1_000,
    capMs = 30_000,
    jitterMs = 100,
  } = options;
 
  let lastError: unknown;
 
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: unknown) {
      lastError = error;
 
      if (!isRetryable(error) || attempt === maxRetries) {
        throw error;
      }
 
      const retryAfterMs = extractRetryAfter(error);
      const backoff = Math.min(baseDelayMs * 2 ** attempt, capMs);
      const jitter = Math.random() * jitterMs;
      const delay = retryAfterMs ?? backoff + jitter;
 
      console.warn(
        `Request failed (attempt ${attempt + 1}/${maxRetries}). ` +
          `Retrying in ${Math.round(delay)}ms...`,
      );
 
      await sleep(delay);
    }
  }
 
  throw lastError;
}
 
function isRetryable(error: unknown): boolean {
  if (error instanceof Response) return false;
  if (typeof error === 'object' && error !== null && 'status' in error) {
    const status = (error as { status: number }).status;
    // Retry on 429 and 5xx only — never retry 4xx client errors
    return status === 429 || status >= 500;
  }
  // Retry network-level errors (no status code)
  return true;
}
 
function extractRetryAfter(error: unknown): number | undefined {
  if (typeof error === 'object' && error !== null && 'headers' in error) {
    const headers = (error as { headers: Headers }).headers;
    const value = headers?.get?.('Retry-After');
    if (value) {
      const seconds = parseFloat(value);
      if (!Number.isNaN(seconds)) return seconds * 1_000;
    }
  }
  return undefined;
}
 
function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

const result = await fetchWithRetry(
  () =>
    fetch('https://api.ocriva.com/upload/YOUR_ORG_ID', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.OCRIVA_API_KEY}` },
      body: formData,
    }).then((res) => {
      if (!res.ok) throw Object.assign(new Error('Request failed'), { status: res.status, headers: res.headers });
      return res.json();
    }),
  { maxRetries: 3, baseDelayMs: 1_000 },
);

// Prefer Retry-After over calculated backoff when available
const retryAfterHeader = response.headers.get('Retry-After');
const waitMs = retryAfterHeader
  ? parseFloat(retryAfterHeader) * 1_000
  : baseDelayMs * 2 ** attempt;
 
await sleep(waitMs);

import { OcrivaClient } from '@ocriva/sdk';
 
const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_API_KEY!,
  maxRetries: 3,   // default; set to 0 to disable
  timeout: 30_000, // per-request timeout in ms
});

import { RateLimitError } from '@ocriva/sdk';
 
try {
  await client.upload.create(orgId, formData);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error(
      `Rate limit exhausted after all retries. ` +
        `Try again in ${error.retryAfter ?? 'a moment'} second(s).`,
    );
  }
}

// Avoid: 50 individual requests, each consuming rate limit quota
for (const file of files) {
  await client.upload.create(orgId, buildFormData(file)); // one request per file
}
 
// Prefer: one batch request regardless of file count (up to 50)
const batchForm = new FormData();
for (const file of files) {
  batchForm.append('files', file);
}
batchForm.append('projectId', projectId);
batchForm.append('templateId', templateId);
 
await client.batch.upload(orgId, batchForm); // single request

const processedEvents = new Set<string>();
 
app.post('/webhook', (req, res) => {
  const { eventId, event, data } = req.body;
 
  if (processedEvents.has(eventId)) {
    // Already handled — acknowledge without re-processing
    return res.status(200).json({ received: true });
  }
 
  processedEvents.add(eventId);
 
  // Safe to process
  handleWebhookEvent(event, data);
 
  res.status(200).json({ received: true });
});

// Wrong: hammers the API every second, exhausts quota in one minute
while (true) {
  const status = await client.processingHistory.get(id, projectId);
  if (status.status === 'completed') break;
  await sleep(1_000); // 1 second — 60 polls per minute = instant rate limit
}
 
// Correct: exponential backoff or use webhooks
let delay = 2_000;
while (true) {
  const status = await client.processingHistory.get(id, projectId);
  if (status.status === 'completed') break;
  await sleep(delay);
  delay = Math.min(delay * 2, 30_000); // back off up to 30 s
}

// Wrong: uses a hardcoded delay that may be shorter than the server requires
} catch (error) {
  await sleep(500); // server said wait 23 s; this will fail again immediately
  return retry();
}
 
// Correct: always honour Retry-After
} catch (error) {
  if (error instanceof RateLimitError && error.retryAfter) {
    await sleep(error.retryAfter * 1_000);
  }
}

// Wrong: retries forever — stalls the process and wastes quota during an outage
async function upload(data: FormData): Promise<unknown> {
  try {
    return await client.upload.create(orgId, data);
  } catch {
    return upload(data); // infinite recursion on persistent errors
  }
}
 
// Correct: bounded retries with backoff
const result = await fetchWithRetry(() => client.upload.create(orgId, data), {
  maxRetries: 3,
});