​

rate_limit_exceeded

​

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly request limit exceeded for your tier (free)",
    "docs_url": "https://docs.avatcado.com/errors/rate_limit_exceeded"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-04-01T00:00:00.000Z
Retry-After: 172800

​

What happened?

• 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:

   Tier	Monthly Limit
   Free	500
   Pro	10,000
   Business	50,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 Avatcado, { RateLimitError } from '@avatcado/node';

const avatcado = new Avatcado('avat_live_your_api_key');
const { data, error } = await avatcado.vat.validate({ vatNumber: '...' });

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

from avatcado import Avatcado, RateLimitError

avatcado = Avatcado("avat_live_your_api_key")

try:
    result = avatcado.vat.validate("...")
except RateLimitError as e:
    print(e.message)
    print(f"Retry after {e.retry_after} seconds")

​

Related errors

• burst_limit_exceeded - Per-minute burst limit exceeded (different from monthly quota)
• unauthorized - API key is invalid (different from being rate limited)