Skip to main content

​
rate_limit_exceeded

HTTP Status: 429 Too Many Requests

​
Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly request limit exceeded for your tier (free)",
    "docs_url": "https://docs.vatly.dev/errors/rate_limit_exceeded"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
The response will also include rate limit headers and a Retry-After header: 
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-04-01T00:00:00.000Z
Retry-After: 172800
For paid tiers, X-RateLimit-Reset reflects your billing anniversary instead of the 1st of the month.

​
What happened?

You’ve used all the requests in your monthly quota. This happens when:
  • Your cumulative requests this month have reached your tier’s limit
  • Cached responses have counted toward your usage (cached results still consume quota)

​
How to fix

  1. Wait for the reset: Check the Retry-After header for the number of seconds to wait, or X-RateLimit-Reset for the exact reset timestamp (your billing period reset date)
  2. Upgrade your tier: Move to a higher tier for more monthly requests:
    TierMonthly Limit
    Free500
    Pro10,000
    Business50,000
  3. Optimize your usage: Implement client-side caching to avoid duplicate lookups for the same VAT number

​
Common mistakes

  • Not tracking usage: Monitor the X-RateLimit-Remaining header on each response to see how many requests you have left
  • Assuming cached results are free: Cached responses still count toward your monthly quota
  • Ignoring the reset date: The X-RateLimit-Reset header tells you exactly when your quota refreshes

​
Catching this error with the SDKs

import Vatly, { RateLimitError } from '@vatly/node';

const vatly = new Vatly('vtly_live_your_api_key');
const { data, error } = await vatly.vat.validate({ vatNumber: '...' });

if (error instanceof RateLimitError) {
  console.log(error.message);
  console.log(`Retry after ${error.retryAfter} seconds`);
}