Rate limits & quotas

Your API key carries one or more rate limits, each with its own window. Every partner route — POST /api/chat/v1, POST /api/chat/v2, GET /api/chat/v2/stream/{runId} and GET /api/chat/v2/quotas — is authenticated with the same x-api-key header and counts against those limits. There are two ways to see where you stand: response headers when a request is rejected, and the quotas endpoint at any time.

Rate-limit headers on 429

When a request is rejected we return 429 with the standard IETF rate-limit headers:

Header	Value
`Retry-After`	Seconds to wait before retrying.
`RateLimit-Limit`	The limit’s ceiling for its window.
`RateLimit-Remaining`	Requests left in the current window (`0` on a 429).
`RateLimit-Reset`	Seconds until the window resets — the same value as `Retry-After`.

Both Retry-After and RateLimit-Reset are relative seconds, computed at the moment of rejection, so you never have to reconcile a timestamp against your own clock. If your key has several limits, these headers describe only the one limit that caused this particular 429 — not your whole budget. Use /quotas for the full picture.

These headers appear only on 429 responses. Successful responses (200) carry no rate-limit headers: with multiple limits in play there is no single limit a success could unambiguously describe, and nothing was rejected. Poll /quotas instead of scraping headers off successful calls.

The body is a JSON envelope:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after the interval in the Retry-After header."
  }
}

Handling a 429

Respect Retry-After rather than retrying on a fixed schedule:

async function callWithRetry(request, maxAttempts = 4) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const response = await request();
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get("Retry-After")) || 1;
    if (attempt === maxAttempts) return response;

    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }
}

A 401 is not a rate-limit signal — it means the key is missing or invalid. Retrying will not help; check the x-api-key header.

Checking your quotas

GET /api/chat/v2/quotas returns every limit configured on your key, so you can throttle before you get rejected.

curl https://www.verahealth.ai/api/chat/v2/quotas \
  -H "x-api-key: YOUR_API_KEY"

{
  "quotas": [
    {
      "label": "requests-per-minute",
      "unit": "requests",
      "limit": 60,
      "remaining": 58,
      "reset": 1755432000000,
      "duration": 60000
    },
    {
      "label": "requests-per-month",
      "unit": "requests",
      "limit": 500000,
      "remaining": 481233,
      "reset": 1757462400000,
      "duration": 2592000000
    }
  ]
}

Field	Description
`label`	The name of the limit as configured for your key.
`unit`	Always `requests` — this API counts requests, not tokens.
`limit`	The ceiling for this limit’s window.
`remaining`	Requests left in the current window.
`reset`	Absolute Unix timestamp in milliseconds at which the current window resets.
`duration`	Window length in milliseconds.

Unlike the 429 headers, reset here is an absolute epoch-milliseconds timestamp, not a duration. Compute the wait as reset - Date.now().

Limits are fixed-window, not calendar-aligned: a window starts at a fixed multiple of duration since the Unix epoch. A 30-day limit therefore does not reset on the 1st of the month — always read reset rather than assuming a calendar boundary.

/quotas is authenticated like any other route and consumes 1 request from each of your limits, exactly as an inference call would. Polling every 1–5 minutes is fine; calling it before every request is not.

Next steps

Quickstart

Make your first call to the Chat API.

Reconnecting a stream

Resume a stream after a disconnect instead of re-asking the question.

API reference

Endpoint schemas and playgrounds for every route.

Support

Email us to raise your limits.

Get Started

Chat API

Agentic API (preview)

Rate-limit headers on 429

Handling a 429

Checking your quotas

Next steps

Quickstart

Reconnecting a stream

API reference

Support

​Rate-limit headers on 429

​Handling a 429

​Checking your quotas

​Next steps

Quickstart

Reconnecting a stream

API reference

Support

Rate-limit headers on 429

Handling a 429

Checking your quotas

Next steps