Rate Limits

Tier-based rate limiting and quota headers

Rate Limits

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

Tiers

Tier	Monthly Requests	Burst Limit (per minute)	Consultation Number	Price
Free	500	20	No	Free
Business	10,000	60	Yes	-
Scale	50,000	120	Yes	-

Rate limit headers

Every authenticated response includes these headers:

Header	Description	Example
X-RateLimit-Limit	Total requests allowed this period	10000
X-RateLimit-Remaining	Requests remaining this period	9542
X-RateLimit-Reset	When the quota resets (ISO 8601)	2026-04-01T00:00:00Z
Retry-After	Seconds to wait before retrying (only on 429/503)	42

Monthly reset

Quotas reset on the first day of each month at 00:00 UTC.

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 telling you exactly how many seconds to wait (1-60).

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.

Test keys

Test keys (vtly_test_ prefix) are exempt from rate limits. They don’t consume quota and don’t return rate limit headers. See Test Mode for details.