Rate Limits

The Shelfforce API enforces rate limits to ensure fair usage and platform stability. Limits are applied per API key over a rolling 60-second window.

Limits by plan

Plan	Analyses / 60s	Reads / 60s	Writes / 60s
Free	5	60	20
Starter	10	120	40
Growth	30	300	80
Pro	60	600	150
Scale	150	1,200	300

Analyses — POST /api/v1/analyses and POST /api/v1/analyses/batch (each image in a batch counts as one analysis request). Reads — All GET endpoints (analyses, products, tasks, places, reports, usage). Writes — All POST and PATCH endpoints except analysis submission (tasks, places, inventory, webhooks).

Rate limit headers

Every API response includes headers showing your current rate limit status:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets

Example response headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 22
X-RateLimit-Reset: 1740312120

Handling rate limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "details": {
      "retryAfter": 12,
      "limit": 30,
      "window": "60s"
    }
  }
}

Best practices

Exponential backoff

When you receive a 429, wait for the duration specified in Retry-After, then retry. If the retry also fails, double the wait time on each subsequent attempt.

Use batch endpoints

Submit up to 20 images in a single batch request instead of making 20 individual calls. This consumes only 1 rate limit slot for writes.

Cache results

Analysis results are permanent. Cache responses locally to avoid redundant GET requests.

Use webhooks

Instead of polling for analysis status, register a webhook to receive notifications when analyses complete. This eliminates repeated GET requests.

Example: Exponential backoff

async function fetchWithBackoff(url: string, options: RequestInit, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get("Retry-After") || "1", 10);
    const backoff = retryAfter * 1000 * Math.pow(2, attempt);
    console.log(`Rate limited. Retrying in ${backoff}ms...`);
    await new Promise((resolve) => setTimeout(resolve, backoff));
  }

  throw new Error("Max retries exceeded");
}

import time
import requests

def fetch_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get("Retry-After", "1"))
        backoff = retry_after * (2 ** attempt)
        print(f"Rate limited. Retrying in {backoff}s...")
        time.sleep(backoff)

    raise Exception("Max retries exceeded")

If you consistently hit rate limits, consider upgrading your plan. Contact hey@shelfforce.ai for custom rate limits on Enterprise plans.

Getting Started

Core Concepts

Guides

Limits by plan

Rate limit headers

Handling rate limits

Best practices

Exponential backoff

Use batch endpoints

Cache results

Use webhooks

Example: Exponential backoff

​Limits by plan

​Rate limit headers

​Handling rate limits

​Best practices

Exponential backoff

Use batch endpoints

Cache results

Use webhooks

​Example: Exponential backoff

Limits by plan

Rate limit headers

Handling rate limits

Best practices

Example: Exponential backoff