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 NumberPrice
Free50020NoFree
Business10,00060Yes-
Scale50,000120Yes-

​
Rate limit headers

Every authenticated response includes these headers:
HeaderDescriptionExample
X-RateLimit-LimitTotal requests allowed this period10000
X-RateLimit-RemainingRequests remaining this period9542
X-RateLimit-ResetWhen the quota resets (ISO 8601)2026-04-01T00:00:00Z
Retry-AfterSeconds 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.