Rate Limiting

To ensure API stability, we enforce the following rate limits:

Tier	Requests/Minute	Burst Capacity	Header Example
Standard	100	50	X-RateLimit-Limit: 100
Partner	500	100	X-RateLimit-Limit: 500
Enterprise	5,000	1,000	X-RateLimit-Limit: 5000

Response Headers

• X-RateLimit-Limit
  Your total request allowance per minute
• X-RateLimit-Remaining
  Remaining requests in current window
• X-RateLimit-Reset
  UTC epoch seconds when limit resets

# Example headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1751006340

Exceeding Limits

When throttled:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "100 requests per minute exceeded"
  }
}

With status 429 Too Many Requests and headers:

Retry-After: 30  # Seconds to wait

Best Practices

1. Monitor Headers
   Track X-RateLimit-Remaining to avoid throttling
2. Handle 429 Gracefully
   Implement retry with Retry-After delay
3. Batching
   Combine requests (e.g., fetch multiple properties in one call)
4. Caching
   Cache static data (property details) for 24h

Note: Authentication errors don't count toward limits. Testing? Request higher limits at it@villra.com.