Rate Limits

Rate Limits by Plan

Burst allows short spikes above the per-minute limit. Useful for application startup or batch operations.

Rate Limit Headers

Every response includes headers showing your current rate limit status:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1704806700
X-RateLimit-Policy: 1000;w=60

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 status code with a Retry-After header:

1HTTP/1.1 429 Too Many Requests
2Retry-After: 23
3Content-Type: application/json
4
5{
6  "error": {
7    "code": "RATE_LIMIT_EXCEEDED",
8    "message": "Rate limit exceeded. Please retry after 23 seconds.",
9    "retryAfter": 23
10  }
11}

SDK Automatic Retries

The TypeScript SDK handles rate limiting automatically. When a 429 response is received, the SDK waits for the Retry-After duration and retries the request up to retryCount times (default: 3). You do not need to implement retry logic yourself.

1import { PuzzleSectionClient, RateLimitError } from '@puzzle-section/sdk';
2
3const client = new PuzzleSectionClient({
4  apiKey: process.env.PUZZLE_SECTION_API_KEY!,
5  retryCount: 3, // default — retries 429 and 5xx automatically
6});
7
8// Rate-limited requests are retried automatically.
9// If retries are exhausted, a RateLimitError is thrown.
10try {
11  const { data, rateLimit } = await client.puzzles.getDaily();
12  console.log(`Remaining: ${rateLimit.remaining}/${rateLimit.limit}`);
13} catch (error) {
14  if (error instanceof RateLimitError) {
15    console.log(`Retry after ${error.retryAfter}s`);
16    console.log(`Limit: ${error.limit}, Remaining: ${error.remaining}`);
17  }
18}

Manual Handling (Raw HTTP)

If you are calling the REST API directly without the SDK, implement exponential backoff:

1async function makeRequestWithRetry<T>(
2  request: () => Promise<T>,
3  maxRetries = 3
4): Promise<T> {
5  for (let attempt = 0; attempt <= maxRetries; attempt++) {
6    try {
7      return await request();
8    } catch (error: any) {
9      if (error?.status === 429 && attempt < maxRetries) {
10        const retryAfter = parseInt(error.headers?.['retry-after'] ?? '5', 10);
11        await new Promise(r => setTimeout(r, retryAfter * 1000));
12        continue;
13      }
14      throw error;
15    }
16  }
17  throw new Error('Max retries exceeded');
18}

Best Practices

• ✓Cache aggressively — Puzzles never change after generation. Cache them for 24+ hours to reduce API calls.
• ✓Monitor headers — Track X-RateLimit-Remaining and slow down before hitting limits.
• ✓Use exponential backoff — When retrying, increase wait times exponentially to avoid hammering the API.
• ✓Batch requests — Use bulk endpoints where available instead of multiple individual requests.
• ✓Spread load — Don't make all requests at the same time. Spread them across the minute.

Activity Tracking

The API tracks your request activity for monitoring and analytics purposes. This data is visible in your dashboard but is not used for pricing or billing.

X-Activity-Month: 123456
X-Activity-Today: 1234
X-Activity-Period: 2026-02-01T00:00:00Z

Important: The Puzzle Section does not meter usage for billing. Plans are based on features and capabilities, not request volumes. Activity tracking is provided for your operational insights only.

Need Higher Rate Limits?

If you're consistently hitting technical rate limits, contact us to discuss custom rate limit configurations for your use case. Enterprise plans include custom rate limits tailored to your infrastructure needs.