Rate Limits
OpenBoxes Lift enforces rate limits on API requests to ensure fair usage and platform stability. Limits are applied per account (per tenant) and depend on your subscription tier and any API add-on on your plan. The limit is shared across all of your API keys — creating additional keys does not increase your quota.
Limits by Tier#
| Tier | Requests per Hour (included) | With an API add-on | Use Case |
|---|---|---|---|
| Shared | 1,000 | 2,000 (API 2×, $30/mo or $288/yr) or 5,000 (API 5×, $70/mo or $672/yr) | Small teams, light integrations |
| Dedicated | 25,000 | 50,000 (API 2×, $175/mo or $1,680/yr) | Production integrations, automated workflows |
| Enterprise | 50,000 | 100,000 (API 2×, +$300/mo) or 200,000 (API 4×, +$525/mo), as contract line items | High-volume, mission-critical systems |
On Shared and Dedicated you raise the limit yourself: go to Billing in the portal, open the Add-ons card, click Browse add-ons and add an API band. One API band can be active at a time (on Shared, to move between 2× and 5×, remove the current band and add the other), and add-ons are available once your subscription is paid — not during the trial. Enterprise agreements include 50,000 requests per hour; the 2× and 4× bands are added to the agreement through sales@openboxes.cloud. See Billing & Plans for how add-ons are charged and cancelled.
Limits apply across all API endpoints combined. There is no per-endpoint breakdown — a request to /api/v1/products and a request to /api/v1/stockMovements both count toward the same hourly quota. The limit is enforced as a rolling hourly allowance (a token bucket that refills continuously), so you do not need to wait for a fixed reset moment — capacity returns steadily as the hour passes.
An API add-on raises this hourly allowance — once it is active, X-RateLimit-Limit reports the new ceiling. It does not change the platform's short-burst protection, which applies to every account alike regardless of plan or add-on, so a larger hourly allowance is still best used by spreading requests over time (see Best Practices below) rather than sending them all at once.
Rate Limit Headers#
Every API response includes headers indicating your current rate limit status:
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1700003600
Content-Type: application/json
| Header | Type | Description |
|---|---|---|
X-RateLimit-Limit |
integer | Your total requests allowed per hour |
X-RateLimit-Remaining |
integer | Requests remaining in the current window |
X-RateLimit-Reset |
integer | Unix timestamp when the window resets |
Checking Your Limits#
Read the rate limit headers from any API response:
curl -s -D - -H "X-API-Key: $OB_API_KEY" \
"https://acme.openboxes.cloud/api/v1/products?max=1" \
-o /dev/null 2>&1 | grep -i "x-ratelimit"
Example output:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 612
X-RateLimit-Reset: 1700003600
Handling 429 Responses#
When you exceed the rate limit, the API returns HTTP 429 Too Many Requests with this JSON body:
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Limit: 1000 requests per hour. Reset at: 1700003600",
"limit": 1000,
"reset_at": 1700003600
}
limit is your hourly ceiling and reset_at is the Unix timestamp when capacity next becomes available (i.e. when your next request will be allowed). Because the allowance refills continuously, that is typically only a few seconds away, not a full hour. The response also includes a Retry-After header indicating how many seconds to wait before retrying:
HTTP/1.1 429 Too Many Requests
Retry-After: 3
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700003600
Implementing Retry Logic#
Always implement exponential backoff when encountering rate limits:
#!/bin/bash
# Simple retry with backoff
MAX_RETRIES=3
RETRY_COUNT=0
make_request() {
response=$(curl -s -w "\n%{http_code}" -H "X-API-Key: $OB_API_KEY" \
"https://acme.openboxes.cloud/api/v1/products?max=25&offset=$1")
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -n -1)
if [ "$http_code" = "429" ]; then
RETRY_COUNT=$((RETRY_COUNT + 1))
if [ $RETRY_COUNT -le $MAX_RETRIES ]; then
wait_time=$((2 ** RETRY_COUNT * 10))
echo "Rate limited. Waiting ${wait_time}s before retry $RETRY_COUNT..."
sleep $wait_time
make_request "$1"
else
echo "Max retries exceeded."
exit 1
fi
else
echo "$body"
fi
}
make_request 0
Best Practices#
Minimize Unnecessary Requests#
Cache responses that do not change frequently:
# Bad: fetching all locations on every sync cycle
# (locations rarely change, burns through your quota)
while true; do
curl -H "X-API-Key: $OB_API_KEY" ".../api/v1/locations"
sleep 60
done
# Good: cache locations, refresh once per hour
curl -H "X-API-Key: $OB_API_KEY" ".../api/v1/locations" > /tmp/locations_cache.json
# Use cached data for the next hour
Use Pagination Efficiently#
Fetch data in reasonable batch sizes instead of making many small requests:
# Bad: fetching one product at a time (100 requests for 100 products)
for id in $product_ids; do
curl -H "X-API-Key: $OB_API_KEY" ".../api/v1/products/$id"
done
# Good: fetch in batches (4 requests for 100 products)
for offset in 0 25 50 75; do
curl -H "X-API-Key: $OB_API_KEY" ".../api/v1/products?max=25&offset=$offset"
done
Monitor Your Usage#
Track the X-RateLimit-Remaining header to detect when you are approaching your limit:
remaining=$(curl -s -D - -H "X-API-Key: $OB_API_KEY" \
"https://acme.openboxes.cloud/api/v1/products?max=1" \
-o /dev/null 2>&1 | grep -i "x-ratelimit-remaining" | tr -d '\r' | cut -d' ' -f2)
if [ "$remaining" -lt 100 ]; then
echo "WARNING: Only $remaining API requests remaining this hour"
fi
Spread Requests Over Time#
Avoid bursting all requests at the start of each hour. Distribute your API calls evenly:
# Bad: sync everything at the top of the hour
0 * * * * /scripts/full_sync.sh # 500 requests in 2 minutes
# Good: stagger sync tasks across the hour
0 * * * * /scripts/sync_products.sh # ~50 requests
15 * * * * /scripts/sync_inventory.sh # ~100 requests
30 * * * * /scripts/sync_orders.sh # ~75 requests
45 * * * * /scripts/sync_movements.sh # ~80 requests
Cache and Batch#
Every API call counts against your limit. Cache data that changes infrequently, batch with pagination, and avoid polling tighter than you need. See Authentication for how requests are authenticated.
Upgrading Your Limit#
If your integration needs exceed your current limit:
| Current Tier | Options |
|---|---|
| Shared (1,000/hr) | Add API 2× (2,000/hr, $30/mo) or API 5× (5,000/hr, $70/mo) under Billing > Add-ons, or move to Dedicated (25,000/hr) |
| Dedicated (25,000/hr) | Add API 2× (50,000/hr, $175/mo) under Billing > Add-ons, or contact sales for Enterprise (50,000/hr included) |
| Enterprise (50,000/hr) | API 2× (100,000/hr, +$300/mo) or 4× (200,000/hr, +$525/mo) as contract line items — contact sales |
Add-ons take effect once the row on your Billing page shows Active (usually within a minute of the purchase; the new ceiling can take a few minutes to reach every request) and are charged pro-rata for the rest of the current period, then with your plan. While an API add-on is active, moving between Shared and Dedicated hosting is arranged with support rather than as a self-serve plan change. Visit the Pricing page for the full list, or contact sales@openboxes.cloud about Enterprise.
Frequently Asked Questions#
Do rate limits apply to the OpenBoxes web UI?
No. Rate limits only apply to API requests (calls to /api/v1/*). Normal browser usage of the OpenBoxes application is not rate-limited.
Which requests are counted?
Every API request (any call to /api/v1/*) counts toward your hourly limit. There is no separate login call to authenticate — you send the X-API-Key header on each request — so cache and batch to stay under your limit.
What happens if I consistently hit the limit?
Persistent rate limit violations usually mean you need an API add-on or a higher tier. Lift does not suspend accounts for hitting rate limits, but sustained 429 responses will degrade your integration's performance.
Can I request a temporary limit increase? Enterprise customers can request a temporary limit increase for a data migration or one-time bulk operation through support.