Illustration of a dial gauge and a stopwatch in rose, purple and blue, for monitoring API usage

Public Holidays API Limits: Monthly Calls and the 429 Error

The HolidaysMap API has two limits. Each plan has a monthly number of calls, and the holidays endpoint also limits how many requests one IP address can send in a minute. Knowing both limits helps you avoid errors and keeps your application working during busy periods.

The monthly call limit

Your plan sets how many calls you can make in a month. The free plan allows 100 calls, Basic allows 10,000, Premium allows 100,000 and Corporate allows 1,000,000. The pricing guide lists the details.

A successful request counts as one call. A request rejected because of invalid parameters is not counted.

When you reach the limit, requests fail with status 401 and this message:

{
  "error": "Account limit exceeded, please upgrade plan for more requests"
}

The dashboard shows your plan’s calls per month and the calls you have made so far. Check it before a busy period, such as a product launch.

The per-minute rate limit

The holidays endpoint accepts up to 100 requests per minute from each IP address. A request over that limit fails with status 429:

{
  "error": "Too many requests, please try again later"
}

The limit is per IP address. If all your servers send requests through one outgoing IP address, they share the same 100 requests a minute. Caching is the fix in most cases.

Cache the holidays

Public holidays for a country and year change rarely. Caching them means your application calls the API once, and then serves the saved copy for every visitor.

  • Cache by country and year. On Premium or higher, make one range request per country and year with start and end. On the free or Basic plan, range requests are not allowed, so cache the dates your application actually checks.
  • Keep the cache for a long time. Holidays for a finished year do not change. For the current and next year, refresh once a month.
  • Do not call the API on every page view. Read from your own storage instead.

Handle the errors in code

For a 429, wait before you retry. A simple approach is to wait a minute and try again, and to stop after a few attempts:

async function fetchWithRetry(url, attempts = 3) {
  for (let attempt = 1; attempt <= attempts; attempt++) {
    const response = await fetch(url);
    if (response.status !== 429) return response;
    await new Promise((resolve) => setTimeout(resolve, 60000));
  }
  throw new Error('Holidays API rate limit still exceeded after retries');
}

For a 401 that mentions the account limit, do not retry. The call will keep failing until the month resets or you upgrade. Show a clear message in your logs, and consider a higher plan if this happens often.

Plan your usage

A quick estimate helps you choose a plan:

  • One call per page view for 10,000 page views a month needs the Basic plan, if you do not cache.
  • One range call per country and year needs only a handful of calls, even for many visitors, if you cache.

Caching changes the numbers far more than a higher plan does, so cache first and then decide whether you need an upgrade.

Next steps