Rate Limits

The Verity API uses rate limiting to ensure fair usage and maintain service quality for all users.

Rate Limit Tiers

Rate Limit Headers

Every API response includes headers to help you track your rate limit status:

Example headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1701878400

Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "hint": "Consider upgrading to a higher plan for increased limits."
  }
}

The response includes a Retry-After header indicating how many seconds to wait:

Retry-After: 30

Best Practices

Implement Exponential Backoff

When rate limited, wait and retry with increasing delays:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Cache Responses

Many API responses can be cached to reduce the number of requests:

• Policy details change infrequently - cache for 1 hour
• Code lookup results - cache for 24 hours
• Use the /policies/changes endpoint to check for updates

Use Batch Endpoints

Use the batch code lookup endpoint to look up multiple codes in a single request (up to 50):

# Instead of multiple requests...
curl /v1/codes/lookup?code=76942
curl /v1/codes/lookup?code=76943
curl /v1/codes/lookup?code=76944

# Use a single batch request
curl -X POST /v1/codes/batch \
  -d '{"codes": ["76942", "76943", "76944"], "include": "rvu,policies"}'

Expensive Operations

Some endpoints have higher rate limit costs:

For example, if your rate limit is 60 requests/minute and you make a policies/compare request (5x cost), it counts as 5 requests against your limit.

Upgrading Your Plan

If you consistently hit rate limits, consider upgrading your plan:

• Starter ($149/mo): 100 req/min, 5,000 calls/month
• Professional ($499/mo): 300 req/min, 25,000 calls/month, FHIR output, semantic search
• Enterprise ($3,000+/mo): 1,000 req/min, 100,000 calls/month, webhooks, SSO

Visit the Usage & Billing page in the Developer Console to upgrade.