Understanding API Rate Limits
Learn how API rate limits work, what your limits are based on your plan, and how to handle rate limit errors when using the Zuro API.
What Are API Rate Limits?
API rate limits control how many API requests you can make per month. They prevent abuse and ensure fair usage across all users. Each subscription plan has different rate limits.
Rate Limits by Plan
Starter Plan
- 1,000 requests/month: Read-only API access
- Resets monthly: On your billing date
- Read operations only: Can't create or update via API
- Good for: Basic integrations and syncing
Professional Plan
- 5,000 requests/month: Full API access
- Resets monthly: On your billing date
- Full CRUD operations: Create, read, update, delete
- Good for: Active integrations and automation
Enterprise Plan
- Unlimited requests: No monthly limit
- No restrictions: Use API as much as needed
- Full access: All API operations
- Good for: High-volume integrations
Free Plan
- No API access: API not available on Free plan
- Upgrade required: Need Starter+ for API access
How Rate Limits Work
Monthly Limits
- Reset date: Your billing date (when you subscribed)
- Example: If you subscribed on the 15th, limits reset on the 15th
- Automatic reset: Happens automatically
- No carryover: Unused requests don't roll over
Request Counting
- Every API call counts: Each request uses one from your limit
- Successful and failed: Both count toward limit
- All endpoints: All API endpoints count
- Per account: Limits are per account, not per key
Rate Limit Headers
API responses include rate limit information in headers:
Response Headers
- X-RateLimit-Limit: Your total monthly limit
- X-RateLimit-Remaining: Requests remaining this month
- X-RateLimit-Reset: When limits reset (Unix timestamp)
Example Headers
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 3421
X-RateLimit-Reset: 1704758400
Handling Rate Limits
Rate Limit Errors
When you exceed your limit, API returns:
- HTTP Status: 429 Too Many Requests
- Error message: "Rate limit exceeded"
- Reset time: When you can make requests again
What to Do
- Wait for reset: Limits reset on your billing date
- Upgrade plan: Get higher limits
- Optimize requests: Reduce unnecessary API calls
- Cache responses: Store data locally to reduce calls
Best Practices
Optimize API Usage
- Batch operations: Combine multiple operations when possible
- Cache data: Store responses to avoid repeated calls
- Use webhooks: Get notified of changes instead of polling
- Efficient queries: Only request data you need
Monitor Usage
- Check headers: Monitor rate limit headers in responses
- Track usage: Keep track of API calls
- Set alerts: Warn when approaching limits
- Plan ahead: Know when you'll need more
Error Handling
- Handle 429 errors: Implement retry logic with backoff
- Respect limits: Don't try to bypass rate limits
- Graceful degradation: Handle rate limits in your app
- User feedback: Inform users if rate limited
Rate Limit Strategies
For High-Volume Apps
- Upgrade to Enterprise: Get unlimited requests
- Use webhooks: Reduce polling needs
- Cache aggressively: Minimize API calls
- Batch operations: Group related requests
For Low-Volume Apps
- Starter plan: 1,000 requests/month may be enough
- Monitor usage: Track to ensure you stay within limits
- Optimize code: Remove unnecessary API calls
- Use efficiently: Make each request count
Troubleshooting
Hitting Limits Too Fast
- Check for loops: Ensure no infinite loops in code
- Review code: Look for unnecessary API calls
- Add caching: Store responses to reduce calls
- Upgrade plan: Get higher limits
Limits Not Resetting
- Check billing date: Verify when limits should reset
- Wait for reset: Ensure billing date has passed
- Contact support: If reset doesn't happen
- Verify subscription: Ensure subscription is active
Unexpected Rate Limits
- Check all API keys: Multiple keys share same limit
- Review usage: Check what's using API
- Monitor headers: Track rate limit info
- Review code: Look for excessive API calls