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 (8x cost), it counts as 8 requests against your limit. Semantic policy search uses the policy-search request multiplier and requires a plan with semantic search enabled.

MCP Usage

MCP requests use the same API usage and rate-limit budget as direct Verity API requests. A single MCP tool call may call multiple underlying API endpoints, so the usage cost depends on the work the tool performs.

For example, verity_coverage_lookup can combine code lookup, policy evidence, prior-authorization checks, claim risk, jurisdiction comparison, and spending evidence. Each downstream Verity API request is counted using the same endpoint cost rules as a direct API call.

MCP traffic appears in the Usage dashboard with source mcp and, when available, the MCP tool name. See the MCP Server guide for authentication and attribution details.

Upgrading Your Plan

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

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

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

Last updated on