Rate limits

Per-key rate limits, headers, and how to handle 429 responses.

vly’s API enforces a per-key rate limit. Default is 60 requests per minute, with burst capacity of ~10 requests in the first second. Plans above Pro raise the limit.

Limits by plan

Plan	Requests / min	Burst
Free	60	10
Pro	600	50
Business	6,000	200
Enterprise	Custom	Custom

Headers

Every API response includes:

X-RateLimit-Limit:     600
X-RateLimit-Remaining: 587
X-RateLimit-Reset:     1713400000

Reset is a Unix timestamp; the limit refills at that time.

Handling 429

When you exceed the limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": {
    "code": "key_rate_limited",
    "message": "Rate limit exceeded. Retry in 12 seconds."
  }
}

Wait Retry-After seconds, then retry. The vly SDKs do this automatically with exponential backoff.

Best practices

Use the SDKs

They handle 429s, retries, and backoff for you.

Batch where possible

Many small calls = high request count. One bigger call = lower.

Cache idempotent responses

Especially for GET endpoints whose data doesn’t change often.

Use webhooks

Don’t poll. Subscribe to events you care about; vly pushes them.

Related

Errors

Full error code reference.

Authentication

Per-key scoping affects rate limits.

SDKs

Auto-handle rate limit retries.