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

Batch Requests

Use array parameters where supported to reduce request count:

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

# Use a single request
/v1/codes/lookup?codes=76942,76943,76944

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 to the pay-as-you-go plan:

• 5x higher rate limits (300 req/min)
• Priority support
• Usage-based billing

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