Rate Limits

Understand request limits and how to handle rate limiting.

Limits by Plan

Plan	Monthly	Daily	Per Minute	Results/Request	GPS Data	Price
Free	1,000	50	10	10	—	$0
Developer	10,000	Unlimited	30	20	—	$9/mo
Pro	100,000	Unlimited	100	25	✓	$29/mo
Enterprise	1,000,000	Unlimited	500	50	✓	$99/mo

Rate Limit Headers

Every API response includes headers to help you track your usage:

Header	Description	Example
X-RateLimit-Limit	Your per-minute request limit	10
X-RateLimit-Remaining	Requests remaining in current window	7
X-RateLimit-Reset	Unix timestamp when limit resets	1704067260

Handling Rate Limits

When you exceed your rate limit, you'll receive a 429 response. Implement exponential backoff to handle this gracefully:

javascript

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

    if (response.status === 429) {
      // Get reset time from header, or use exponential backoff
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitMs = resetTime
        ? (parseInt(resetTime) * 1000) - Date.now()
        : Math.pow(2, attempt) * 1000;

      console.log(`Rate limited. Waiting ${waitMs}ms...`);
      await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 1000)));
      continue;
    }

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

// Usage
const response = await fetchWithRetry(
  'https://golfly.dev/api/v1/courses',
  { headers: { 'x-api-key': API_KEY } }
);

Best Practices

Cache responses

Golf course data doesn't change frequently. Cache responses for at least 24 hours to reduce API calls.

Use your plan's maximum limit

The API automatically applies your plan's max limit per request (Free: 10, Developer: 20, Pro: 25, Enterprise: 50).

Filter server-side

Use query parameters like state and min_rating instead of fetching all data and filtering client-side.

Monitor your usage

Check the dashboard to monitor your API usage and upgrade before hitting limits.

Need More?

Enterprise customers can request bulk data exports or custom rate limits.