Rate Limits
Understand API rate limits and how to handle them gracefully.
Rate Limit Tiers
Rate limits vary by plan and endpoint type:
| Plan | API Requests | Verification Links | Webhooks |
|---|---|---|---|
| Starter | 100/minute | 20/minute | 5 endpoints |
| Professional | 500/minute | 100/minute | 20 endpoints |
| Business | 2,000/minute | 500/minute | 50 endpoints |
| Enterprise | Custom | Custom | Unlimited |
Rate Limit Headers
Every API response includes rate limit information in the headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when window resets |
Retry-After | Seconds to wait before retrying (only on 429) |
Handling Rate Limits
When you exceed the rate limit, the API returns a 429 status code:
Rate Limit Best Practices
Monitor rate limit headers
Track remaining requests and back off before hitting the limit.
Implement exponential backoff
When rate limited, wait and retry with increasing delays.
Use webhooks instead of polling
Subscribe to webhooks rather than polling for verification status.
Cache responses
Cache verification results to reduce API calls.
Batch operations
Use bulk endpoints when available instead of individual requests.
Implementation Example
Request Queuing
For high-volume applications, implement a request queue:
Monthly Verification Limits
In addition to rate limits, each plan has a monthly verification quota:
| Plan | Monthly Verifications | Overage Rate |
|---|---|---|
| Starter | 100 | $2.50/verification |
| Professional | 1,000 | $2.00/verification |
| Business | 10,000 | $1.50/verification |
| Enterprise | Custom | Custom |
Check your usage in the dashboard or via API:
Increasing Your Limits
If you need higher rate limits or verification quotas:
Upgrade Your Plan
Higher tier plans include increased rate limits and verification quotas. View pricing →
Contact Owl Eyes Team
For enterprise needs or custom limits, contact our team. Contact us →
Temporary Increase
Planning a launch? Request a temporary limit increase via support.
Sandbox Rate Limits
The sandbox environment has more relaxed rate limits for testing:
| Resource | Sandbox Limit |
|---|---|
| API Requests | 1,000/minute |
| Verification Links | 500/minute |
| Monthly Verifications | Unlimited (test mode) |
Request Size Limits
In addition to rate limits, the API enforces the following size limits for uploads:
| Resource Type | Maximum Size | Recommendations |
|---|---|---|
| Document Images | 10 MB | JPEG quality 80-85%, max 4096×4096px |
| Selfie Images | 5 MB | JPEG quality 85%, max 2048×2048px |
| Liveness Video | 20 MB | H.264 codec, 720p, 30fps |
| Voice Samples | 5 MB per sample | WAV format, 16kHz mono |
| KYB Documents | 10 MB | PDF or compressed images |
| Request Body (total) | 10 MB | Compress images before base64 encoding |