Rate Limits

The HeyVisa API uses per-key, per-minute rate limits. Limits scale with your plan, and bursting above the limit returns a structured 429 response that includes a precise Retry-After hint.

Limits by plan

Plan	Requests / hour	Reports / month	Concurrency
Free	60	10	1
Pro	1,000	500	10
Team	5,000	2,500	30
Enterprise	Custom	Unlimited	Custom (typically 100+)

Limits are evaluated in a rolling window. Test keys (hv_test_) have the same limits as your live plan to keep behaviour predictable across environments.

Response headers

Every successful response includes the current state of your rate window:

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1718099400

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window.
X-RateLimit-Remaining	Requests left before throttling.
X-RateLimit-Reset	Unix timestamp at which the window resets.

When you exceed the limit

We return 429 Too Many Requests with both a Retry-After header (seconds) and a structured error body.

http

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718099400

{
  "error": {
    "type": "rate_limited",
    "code": "request_rate_exceeded",
    "message": "You have exceeded the per-minute request limit. Retry in 23 seconds.",
    "retry_after": 23
  }
}

Best practices

Backoff strategy

Implement exponential backoff with jitter. Wait Retry-After seconds on the first retry, then double the delay (capped at 60 s) and add 0–500 ms of random jitter to avoid thundering-herd behaviour after an outage.

For bulk operations, prefer batch submissions over a tight loop of single-report calls — batches count as one request against the rate limit.