Rate Limits

The FuelPrice API implements rate limiting to ensure fair usage and maintain service quality for all users.

Limits

Rate limiting is applied per API key across all endpoints.

30 requests per minute is enough for any normal usage pattern, including fetching all cities, suburbs, stations, and fuel types on initial load. If you are hitting this limit regularly, your application is likely making unnecessary repeated requests that should be cached.

Rate Limit Errors

When you exceed the rate limit, the API returns a 429 Too Many Requests response.

{
  "error": "Rate limit exceeded. You are allowed 30 requests per minute. Please slow down and try again shortly.",
  "code": "rate_limit_exceeded"
}

Handling Rate Limits

When you receive a 429, wait at least 60 seconds before retrying. Using exponential backoff is good practice:

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

    if (response.ok) {
      return response.json()
    }

    if (response.status === 429) {
      const delay = Math.pow(2, i) * 1000 // 1s, 2s, 4s
      console.log(`Rate limited. Retrying in ${delay}ms...`)
      await new Promise(resolve => setTimeout(resolve, delay))
      continue
    }

    throw new Error(`HTTP ${response.status}`)
  }

  throw new Error('Max retries exceeded')
}

const data = await fetchWithRetry('https://api.fuelprice.io/v1/cities', {
  headers: { 'Authorization': `Bearer ${token}` }
})

Best Practices

The best way to avoid rate limits entirely:

1. Cache responses locally — Fuel price data updates once per day. Fetch it on a schedule and serve from your own database. See Best Practices.

2. Don't poll the API — Set up a daily refresh job instead of requesting data on every user action.

3. Fetch once on startup — Load cities, suburbs, stations, and fuel types once when your application starts, not on every request your users make.