Rate Limits

Rate limits protect the API from abuse and ensure fair usage for all users.

Understanding Limits

Plan	Requests per Hour	Per End-Customer
Starter	1,000	Shared
Growth	10,000	1,000 each
Enterprise	Custom	Custom

Testing environment has higher rate limits to support development and testing.

Rate Limit Headers

Every response includes these headers:

Header	Description	Example
X-RateLimit-Limit	Maximum requests per window	1000
X-RateLimit-Remaining	Requests remaining	742
X-RateLimit-Reset	Unix timestamp when window resets	1706616000

< X-RateLimit-Limit: 1000
< X-RateLimit-Remaining: 742
< X-RateLimit-Reset: 1706616000

Handling 429 Errors

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "object": "error",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "details": {
      "limit": 1000,
      "window": "1 hour",
      "resetAt": "2025-01-30T13:00:00Z"
    }
  }
}

The response includes a Retry-After header with the number of seconds to wait:

< HTTP/2 429
< Retry-After: 60

Implementing Exponential Backoff

TypeScript

async function fetchWithBackoff<T>(
  url: string,
  options: RequestInit,
  maxRetries = 5
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get("Retry-After") || "60",
        10
      );
      // Add jitter to prevent thundering herd
      const jitter = Math.random() * 1000;
      const waitTime = retryAfter * 1000 + jitter;

      console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
      await new Promise((resolve) => setTimeout(resolve, waitTime));
      continue;
    }

    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }

    return response.json();
  }

  throw new Error("Max retries exceeded");
}

// Usage (testing environment example)
const data = await fetchWithBackoff(
  "https://embedded-api.testing.mapademics.com/v1/skills",
  {
    headers: { "X-API-Key": process.env.MAPADEMICS_TEST_KEY! },
  }
);

Python

Best Practices

1. Cache Responses

Many API responses are cacheable. Cache aggressively to reduce API calls:

const skillsCache = new Map<string, { data: Skill; expires: number }>();

async function getSkill(skillId: string): Promise<Skill> {
  const cached = skillsCache.get(skillId);
  if (cached && cached.expires > Date.now()) {
    return cached.data;
  }

  // For production, include X-End-Customer-API-Key header as well
  const response = await fetch(
    `https://embedded-api.mapademics.com/v1/skills/${skillId}`,
    { headers: { "X-API-Key": LIVE_KEY, "X-End-Customer-API-Key": CUSTOMER_KEY } }
  );
  const { data } = await response.json();

  // Cache for 1 hour
  skillsCache.set(skillId, {
    data,
    expires: Date.now() + 60 * 60 * 1000,
  });

  return data;
}

Recommended cache durations:

Endpoint	Cache Duration
Skills Library	24 hours
Labor Market Data	1 hour
Extraction Results	Indefinite (immutable)

2. Batch Requests Where Possible

Instead of making individual requests, use batch-capable endpoints:

# Bad: 5 separate requests
GET /v1/labor-market-intelligence/soc?socCodes=15-1251
GET /v1/labor-market-intelligence/soc?socCodes=15-1252
GET /v1/labor-market-intelligence/soc?socCodes=15-1253
GET /v1/labor-market-intelligence/soc?socCodes=15-1254
GET /v1/labor-market-intelligence/soc?socCodes=15-1255

# Good: 1 batched request
GET /v1/labor-market-intelligence/soc?socCodes=15-1251,15-1252,15-1253,15-1254,15-1255

3. Use Sparse Fieldsets

Request only the fields you need to reduce response size and processing time:

# Only get name, socCode, and salary data
GET /v1/labor-market-intelligence/cip/11.0701?fields=name,socCode,laborMarketData

4. Monitor Your Usage

Track your rate limit consumption proactively:

class RateLimitMonitor {
  private remaining: number = Infinity;
  private resetAt: number = 0;

  updateFromResponse(response: Response) {
    this.remaining = parseInt(
      response.headers.get("X-RateLimit-Remaining") || "1000"
    );
    this.resetAt = parseInt(
      response.headers.get("X-RateLimit-Reset") || "0"
    ) * 1000;
  }

  shouldThrottle(): boolean {
    // Start throttling at 10% remaining
    return this.remaining < 100;
  }

  getWaitTime(): number {
    if (this.remaining > 0) return 0;
    return Math.max(0, this.resetAt - Date.now());
  }
}

5. Implement Circuit Breakers

Prevent cascading failures when hitting rate limits:

class CircuitBreaker {
  private failures = 0;
  private lastFailure = 0;
  private readonly threshold = 5;
  private readonly timeout = 60000; // 1 minute

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.isOpen()) {
      throw new Error("Circuit breaker is open");
    }

    try {
      const result = await fn();
      this.reset();
      return result;
    } catch (error) {
      this.recordFailure();
      throw error;
    }
  }

  private isOpen(): boolean {
    if (this.failures < this.threshold) return false;
    if (Date.now() - this.lastFailure > this.timeout) {
      this.reset();
      return false;
    }
    return true;
  }

  private recordFailure() {
    this.failures++;
    this.lastFailure = Date.now();
  }

  private reset() {
    this.failures = 0;
  }
}

Increasing Your Limits

If you need higher rate limits:

1. Optimize first - Implement caching, batching, and other best practices

2. Monitor usage - Identify peak usage patterns

3. Contact us - Email [email protected] to discuss your needs

Enterprise plans include:

• Custom rate limits

• Dedicated infrastructure

• Priority support

• SLA guarantees