Rate Limits
Rate limits are enforced per API key to ensure fair usage and system stability. Understand your quotas and how to handle capacity constraints.
Limit tiers
Limits are applied per API key. If you need higher throughput, you can distribute workloads across multiple keys (subject to plan limits) or upgrade to a higher tier.
| Tier | Per minute | Per hour | Max image |
|---|---|---|---|
| Free | 5 | 50 | 5 MB |
| Pro | 30 | 200 | 20 MB |
| Enterprise | 120 | 2,000 | 50 MB |
Checking usage
Retrieve your current consumption and remaining quota by polling the rate limit endpoint.
curl https://oceanir.ai/api/rate-limit \
-H "x-api-key: YOUR_API_KEY"Every API response includes RFC 9331 RateLimit andRateLimit-Policy plus the legacyX-RateLimit-Limit,X-RateLimit-Remaining, andX-RateLimit-Reset headers. 429 responses also send Retry-After. GraphQL is not used; this REST convention is the one to implement against.
Handling 429 Errors
When a threshold is exceeded, the gateway returns a 429 Too Many Requests response.
{
"success": false,
"error": "Rate limit exceeded.",
"retry_after": 60
}Best practices
Exponential Backoff
Implement a retry strategy that increases delay between attempts after receiving a 429 response.
Caching
Store results locally for identical images. The Orca engine returns deterministic results for identical pixels.
Batching
For high-volume archival tasks, distribute requests over longer periods to stay within hourly quotas.
Monitoring
Keep track of usage via the Settings dashboard.