8. Rate Limiting & Quotas Guide

To guarantee high availability, system stability, and fair usage across all applications, the Countries API enforces IP-based rate limiting on all /api/* endpoints.

Response Headers

Every response returned by the API contains HTTP response headers indicating your remaining request quota in real-time:

HTTP 429 Error Structure

When an application exceeds the 100 requests limit within 15 minutes, the API responds with HTTP 429 Too Many Requests and the following JSON payload:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests from this IP, please try again after 15 minutes."
  }
}

Handling Rate Limits in Frontend & Backend Code

JavaScript Fetch API (Handling 429 & Retry):

async function fetchCountriesWithRetry(endpoint, apiKey, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(endpoint, {
      headers: { 'x-api-key': apiKey }
    });

    if (res.status === 429) {
      const retryAfterSeconds = parseInt(res.headers.get('Retry-After') || '60', 10);
      console.warn(`Rate limit reached. Retrying in ${retryAfterSeconds}s...`);
      await new Promise(resolve => setTimeout(resolve, retryAfterSeconds * 1000));
      continue;
    }

    return await res.json();
  }
  throw new Error('Max retries exceeded due to rate limits.');
}

Axios Interceptor Handling:

axios.interceptors.response.use(
  response => response,
  async error => {
    if (error.response && error.response.status === 429) {
      const waitSeconds = error.response.headers['retry-after'] || 60;
      await new Promise(r => setTimeout(r, waitSeconds * 1000));
      return axios.request(error.config);
    }
    return Promise.reject(error);
  }
);

Best Practices

• Cache API Responses: Static country information (e.g., capitals, ISO codes) rarely changes. Store results in localStorage or server cache (Redis/Memory) to minimize API requests.
• Use Field Filtering: Request only needed fields with ?fields=name,capital,population to keep bandwidth low and responses ultra-fast.
• Monitor Remaining Quota: Read the X-RateLimit-Remaining header in your client application to throttle traffic before hitting HTTP 429 errors.