Rate Limits & Pricing

Understanding rate limits, monthly quotas, and pricing for the Nameday API.

Overview

The Nameday API uses two types of rate limiting to ensure fair usage and system stability:

1. Per-minute rate limit: Prevents burst abuse and ensures the service remains responsive
2. Monthly quota: Limits the total number of API calls per billing period

Rate Limits

Per-Minute Limits

All API keys are limited to 60 requests per minute, regardless of tier. This applies to both free and paid plans.

Monthly Quotas

Monthly quotas determine how many API calls you can make each billing period:

Response Headers

Every API response includes rate limit information in the headers. Use these headers to track your usage and implement smart retry logic:

Example Response

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1704067260
X-Quota-Limit: 1000
X-Quota-Remaining: 950
Content-Type: application/json

{
  "namedays": [...]
}

Handling Rate Limits

429 Too Many Requests

When you exceed the per-minute rate limit, the API returns a 429 status code:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067320
Retry-After: 45

{
  "error": "Too many requests",
  "message": "Rate limit exceeded. Please wait before making more requests.",
  "retryAfter": 45
}

Wait for the number of seconds specified in the Retry-After header or retryAfter field before making another request.

402 Payment Required

When free tier users exceed their monthly quota, they receive a 402 status code:

HTTP/1.1 402 Payment Required
X-Quota-Limit: 1000
X-Quota-Remaining: 0

{
  "error": "Free tier limit exceeded. Upgrade at name.birrday.com/api-dashboard",
  "upgrade": "https://name.birrday.com/api-dashboard"
}

Upgrade to Pro for unlimited API calls or wait until your quota resets at the start of the next billing period.

Pricing Tiers

Choose the plan that fits your needs. All plans include access to all countries and traditions.

Best Practices

1. Cache responses — Nameday data doesn't change frequently. Cache API responses in your application to reduce redundant calls.
2. Batch requests — Use the month parameter to fetch multiple days at once rather than making individual requests for each day.
3. Handle errors gracefully — Implement exponential backoff for 429 errors and respect the Retry-After header.
4. Monitor usage — Check the X-Quota-Remaining header to track how many calls you have left for the month.

Implementing Retry Logic

Here's an example of handling rate limits with exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, i) * 1000;

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

    if (response.status === 402) {
      throw new Error('Monthly quota exceeded. Please upgrade your plan.');
    }

    return response;
  }

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

Checking Remaining Quota

You can monitor your remaining quota by inspecting the response headers:

const response = await fetch('https://name.birrday.com/api/v1/namedays?country=GR', {
  headers: {
    'x-api-key': 'nd_live_your_key_here'
  }
});

// Check rate limit status
const rateLimitRemaining = response.headers.get('X-RateLimit-Remaining');
const rateLimit = response.headers.get('X-RateLimit-Limit');
console.log(`Rate limit: ${rateLimitRemaining}/${rateLimit} per minute`);

// Check monthly quota (free tier only)
const quotaRemaining = response.headers.get('X-Quota-Remaining');
if (quotaRemaining) {
  const quota = response.headers.get('X-Quota-Limit');
  console.log(`Monthly quota: ${quotaRemaining}/${quota} remaining`);

  // Warn when approaching limit
  if (parseInt(quotaRemaining) < 100) {
    console.warn('Approaching monthly quota limit!');
  }
}

Upgrading to Pro

To upgrade from the free tier to Pro and unlock unlimited API calls:

1. Visit the API Dashboard
2. Click the "Upgrade to Pro" button
3. Complete payment via Stripe
4. Start making unlimited API calls immediately!

Your subscription renews automatically each month and can be cancelled at any time from the dashboard.