Fuel Price | API

Rate Limits

The FuelPrice API implements rate limiting to ensure fair usage and maintain service quality for all users. This guide explains how rate limits work and how to handle them in your application.

Rate limiting is currently being implemented. Once active, the API will return specific error responses when limits are exceeded. This documentation will help you prepare for handling these scenarios.

Current Status

We are in the process of implementing rate limits across all API endpoints. Once implemented, you will receive standardized error responses when your application exceeds the allowed request limits.

Rate limits will be based on:

  • Requests per minute - Short-term burst protection
  • Requests per hour - Sustained usage limits
  • API key tier - Different limits for different subscription levels

Rate Limit Errors

When you exceed a rate limit, the API will return a 429 Too Many Requests status code with details about the limit and when you can retry.

Error Response

When rate limited, you'll receive a 429 status code with an error response containing:

  • error: Human-readable error message
  • code: rate_limit_exceeded
  • retry_after: Seconds until you can retry

The response will also include helpful headers to track your rate limit status.

Rate Limit Error Response

{
  "error": "Rate limit exceeded. Please retry after 60 seconds.",
  "code": "rate_limit_exceeded",
  "data": {
    "retry_after": 60
  }
}

Rate Limit Headers

The API includes headers in every response to help you track your rate limit status:

  • Name
    X-RateLimit-Limit
    Description

    The maximum number of requests allowed in the current time window.

  • Name
    X-RateLimit-Remaining
    Description

    The number of requests remaining in the current time window.

  • Name
    X-RateLimit-Reset
    Description

    Unix timestamp when the rate limit window resets.

  • Name
    Retry-After
    Description

    Number of seconds to wait before making another request (only present when rate limited).

About Header Standardization: The X-RateLimit-* headers follow common industry practice used by major APIs like GitHub and Twitter, but are not officially standardized. The Retry-After header is an official HTTP standard (RFC 7231). An IETF draft standard for rate limit headers is in progress but not yet finalized.

Handling Rate Limits

Exponential Backoff

When you receive a 429 error, implement exponential backoff to gradually increase wait times between retries:

POST
/v1/cities
# First request
curl -G https://api.fuelprice.io/v1/cities \
  -H "Authorization: Bearer {token}" \
  -w "\nHTTP Status: %{http_code}\n"

# If 429 received, wait and retry
sleep 60
curl -G https://api.fuelprice.io/v1/cities \
  -H "Authorization: Bearer {token}"

Best Practices

To avoid hitting rate limits:

  1. Cache API responses - Store data in your database and serve from cache when possible. See Best Practices for detailed caching strategies.

  2. Monitor headers - Check X-RateLimit-Remaining to track how close you are to the limit.

  3. Implement backoff - Use exponential backoff when you receive 429 errors.

  4. Batch requests - Where possible, request multiple resources in fewer API calls. (COMING SOON)

Learn more about API best practices