Retry & rate limits

Defaults

• Max retries: 3 (configurable via maxRetries).
• Request timeout: 30 seconds (configurable via timeout).
• Backoff: exponential — 500ms, 1s, 2s, 4s, capped at 8s, plus up to 200ms of jitter.
• Retry triggers: network errors, request timeouts, and any 5xx response.
• 429s: the SDK sleeps for retryAfter seconds, then retries.

Tune the retry cap

import { CStarClient } from '@cstar.help/js';

const cstar = new CStarClient({
  apiKey: process.env.CSTAR_KEY,
  teamId: process.env.CSTAR_TEAM_ID,
  maxRetries: 5,        // Default 3
  timeout: 60_000       // Default 30000 ms
});

Drop maxRetries to 0 if you want to handle retries yourself in a job queue. The SDK will throw on the first failure.

Rate limits

• Secret keys (sk_live_*, sk_test_*): 1000 req/hour.
• Publishable keys (pk_live_*, pk_test_*): 100 req/hour.

Every response carries the limit on response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1714508400      # Unix timestamp when the window resets
X-RateLimit-Window: 3600           # Window size in seconds

Catching 429 yourself

The SDK retries 429s up to maxRetries times. After that you get a typed CStarRateLimitError — useful when you want to push the retry to a queue rather than blocking the call site.

import { CStarRateLimitError } from '@cstar.help/js';

try {
  await cstar.tickets.create(payload);
} catch (e) {
  if (e instanceof CStarRateLimitError) {
    // e.retryAfter is in seconds (default 60 if the server didn't say)
    queue.enqueue('retry-ticket-create', payload, { delay: e.retryAfter * 1000 });
    return;
  }
  throw e;
}