Rate Limits & Quotas

The VIN Decoder API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits vary by subscription tier.

Subscription Tiers

Rate Limit Headers

Every API response includes headers to help you track your rate limit status:

Example Response Headers

Handling Rate Limits

When You Hit a Rate Limit

If you exceed your rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "detail": "Rate limit of 60 requests per minute exceeded",
  "retry_after": 15
}

The response includes:

• Retry-After header: Seconds to wait before retrying
• Error details: Which limit was exceeded

Best Practices

// JavaScript example
fetch(url, options)
  .then(response => {
    const remaining = response.headers.get('X-RateLimit-Remaining');
    const quotaUsed = response.headers.get('X-Monthly-Quota-Used');

    console.log(`Rate limit remaining: ${remaining}`);
    console.log(`Monthly quota used: ${quotaUsed}`);

    if (remaining < 10) {
      console.warn('Approaching rate limit!');
    }

    return response.json();
  });

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

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
    console.log(`Rate limited. Waiting ${retryAfter} seconds...`);

    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }

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

Quota Management

Check Your Usage

Monitor your current usage with the usage endpoint:

GET /api/v1/user/usage

Response:
{
  "subscription_tier": "professional",
  "monthly_limit": 5000,
  "used_this_month": 1523,
  "remaining": 3477,
  "percentage_used": 30.46,
  "reset_date": "2024-02-01T00:00:00Z",
  "daily_usage": {
    "today": 45,
    "yesterday": 62,
    "last_7_days": 312
  }
}

Quota Reset

• Monthly quotas reset on the 1st of each month at 00:00 UTC
• Unused quota does not roll over
• Rate limits reset every minute/hour based on the limit type

Exceeding Monthly Quota

When you exceed your monthly quota:

1. You'll receive a 429 error with quota details
2. Consider upgrading your subscription
3. Or wait until the next month for quota reset