Skip to main content

​
Rate Limits

Vatly uses tier-based monthly rate limits. Every authenticated response includes rate limit headers so you always know where you stand.

​
Tiers

TierMonthly RequestsBurst Limit (per minute)Consultation Number
Free50020Yes
Pro10,00060Yes
Business50,000120Yes

​
Rate limit headers

Validation responses include these headers on 2xx and monthly-quota 429 paths. Burst 429 responses include only X-Burst-Limit, X-Burst-Remaining, and Retry-After. Rate routes (/v1/rates) return only X-Burst-* (they do not count against monthly quota). Test-mode responses return no rate-limit headers.
HeaderDescriptionExample
X-RateLimit-LimitTotal requests allowed this period10000
X-RateLimit-RemainingRequests remaining this period9542
X-RateLimit-ResetWhen the quota resets (ISO 8601). Free tier: 1st of next month. Paid tiers: billing anniversary2026-04-20T00:00:00.000Z
X-Burst-LimitPer-minute burst limit for your tier60
X-Burst-RemainingBurst requests remaining this minute58
Retry-AfterSeconds to wait before retrying (only on 429/503). Burst: remaining seconds in the current 60-second window. Monthly: seconds until the period reset1-60 or 86400

​
Monthly reset

  • Free tier: quotas reset on the first day of each month at 00:00 UTC.
  • Pro and Business tiers: quotas reset on your billing anniversary. If you subscribe on March 20th, your quota resets on the 20th of each month.
The X-RateLimit-Reset header always reflects your next reset date.

​
Burst limits

In addition to monthly quotas, each tier has a per-minute burst limit. This protects the API from accidental tight loops and misconfigured clients. When you exceed the burst limit, the API returns a 429 status with the burst_limit_exceeded error and a Retry-After header equal to the remaining seconds in the current 60-second window.

​
What happens when you hit the monthly limit

When your monthly quota is exhausted, the API returns a 429 status with the rate_limit_exceeded error: 
{
  "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 X-RateLimit-Remaining header will be 0 and X-RateLimit-Reset will tell you when your quota refreshes. The Retry-After header contains the number of seconds until the monthly reset.
Cached responses also count toward your monthly usage. See Caching for details.

​
Batch validation usage

Batch requests charge based on the number of unique VAT numbers in the request. Duplicates within a single batch are free.
  • A batch of ["NL123456789B01", "NL123456789B01", "DE987654321"] consumes 2 requests from your monthly quota
  • The entire batch is rejected with rate_limit_exceeded if your remaining quota is less than the unique count. No partial execution occurs.
  • Each batch request counts as 1 hit against the per-minute burst limit, regardless of how many VAT numbers it contains

​
Test keys

Test keys (vtly_test_ prefix) are exempt from monthly quota and burst limits. They don’t consume quota, don’t trigger 429s, and don’t return rate limit headers. Async endpoints reject test keys; use a live key for async testing. See Test Mode for details.