Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt

Use this file to discover all available pages before exploring further.

All API requests authenticated via API key or OAuth token are subject to rate limiting. Limits are enforced per organization — every API key and OAuth token issued to your organization shares one rate-limit budget. Creating additional credentials does not raise your limit.
Authentication methodHeaderApplies to
API keyx-auth-apikeyDeveloper and Partner Developer accounts
OAuth tokenx-auth-access-tokenOAuth-authorized applications

How limits work

Rhombus uses a token bucket algorithm. Two values govern your throughput:
  • A sustained refill rate (requests per second) — your steady-state ceiling.
  • A burst capacity, roughly 10× the refill rate by default — headroom that absorbs short spikes.
Bursts succeed instantly while the bucket has tokens. Once the bucket drains, sustained traffic above the refill rate returns 429s until the bucket refills. Default rates apply to all organizations. To request a higher limit, contact Rhombus support.

Throttled responses

When your request is rate limited, the API returns a 429 status with a Retry-After header:
HTTP 429 response
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: text/plain

Too many api requests. Enhance your calm.
DetailValue
Status code429
Retry-After headerSeconds to wait before retrying. Computed from your organization’s refill rate; always at least 1 second.
BodyToo many api requests. Enhance your calm.
Do not immediately retry on a 429. Repeated requests while rate limited continue to be rejected and do not reset your limit window.

Handling rate limits

1

Read the Retry-After header

The Retry-After header tells you exactly how many seconds to wait, computed from your organization’s refill rate. Always prefer this value over hardcoded delays.
2

Pause requests

Stop sending requests for the duration specified in the header.
3

Retry your request

After the wait period, retry the original request.

Retry strategy

Use exponential backoff with jitter for the most resilient integration:
Backoff formula
delay = min(base_delay × 2^attempt + random_jitter, max_delay)
ParameterRecommended value
Base delay1 second
Max delay60 seconds
Max retry attempts5–10
JitterRandom 0–1 second
retry_with_backoff.py
import time
import random
import requests

def call_api(url, headers, payload, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 60))
            time.sleep(wait)
            continue

        if response.status_code >= 500:
            delay = min(1 * (2 ** attempt) + random.random(), 60)
            time.sleep(delay)
            continue

        # 4xx errors (other than 429) are not retryable
        response.raise_for_status()

    raise Exception("Max retries exceeded")

# Usage
result = call_api(
    url="https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList",
    headers={
        "x-auth-scheme": "api-token",
        "x-auth-apikey": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    payload={}
)

When to retry

ResponseAction
200–299Success — no retry needed
429Wait for Retry-After seconds, then retry
5xxTransient server error — retry with exponential backoff
4xx (not 429)Client error — fix the request, do not retry
The rate limiting system is fail-open. If the rate-limit service or its backing store is unavailable, your request is allowed through. Do not rely on this behavior — always design your integration to respect limits.

What changed

Recent rate-limiter improvements are now live:
  • Limits are now pooled across all of an organization’s credentials. Distributing traffic across multiple API keys no longer increases throughput.
  • Short bursts above your sustained rate are now allowed.
  • Retry-After reflects the true wait time computed from your refill rate, instead of a fixed 60 seconds.

Alert notification throttling

Alert notifications (distinct from API rate limits) have a configurable minimum interval between consecutive alerts of the same type for a given device. This prevents alert fatigue from high-frequency events like motion detection.
IntervalSeconds
1 minute60
2 minutes120
5 minutes (default)300
10 minutes600
20 minutes1200
30 minutes1800
1 hour3600
Configure this per policy and per activity type. During the backoff window, duplicate alerts for the same device and activity type are suppressed server-side.
Alerts with new identity information — such as a different recognized face or license plate — bypass the backoff and are delivered immediately, even within the suppression window.
Last modified on April 29, 2026