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:00Z
Retry-After: 2073600

​
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 (first of each month, UTC)
  2. Upgrade your tier — Move to a higher tier for more monthly requests:
    TierMonthly Limit
    Free500
    Business10,000
    Scale50,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
  • burst_limit_exceeded — Per-minute burst limit exceeded (different from monthly quota)
  • unauthorized — API key is invalid (different from being rate limited)