Errors and Status Codes

The REST API reports a failed request in one of two ways, so check both:

1. An HTTP error status when the request itself can't be processed: malformed JSON, a missing field, a credential problem, a permission denial or a rate limit. The body has "error": true and a machine-readable errorCode.
2. HTTP 200 with "error": true when the request was valid but the action failed or was refused, for example a role you're not allowed to assign. The reason is in errorMsg:

{
  "error": true,
  "errorMsg": "User not permitted to generate an api token for the specified role"
}

A request succeeded only when the status is 2xx and error is false.

The response envelope

Every JSON response from the REST API carries the same three fields alongside its data:

Error responses have the same body on every host: the REST API, the media hosts, WebSocket handshakes and the MCP server.

Every error response carries errorCode, a stable code to branch on, next to errorMsg, a message to show or log. Codes are never renamed or removed, but new ones are added: handle a code you don't recognize by its HTTP status.

Every response with an error status has the same body. msg is the HTTP reason phrase, kept for older clients; status repeats the HTTP status; timestamp is when the error happened, in Unix epoch milliseconds; txid is the request ID to quote to support, also sent as the x-rhombus-txid header:

{
  "msg": "Forbidden",
  "error": true,
  "errorCode": "FUNCTIONALITY_REQUIRED",
  "errorMsg": "Your role is missing a functionality this action requires.",
  "status": 403,
  "timestamp": 1791367200000,
  "txid": "yJ2kQw8LTaO1xX4hVd7mPA"
}

The codes the API returns today:

Fields whose value is null are left out of responses, so treat a missing field as null. Empty lists are still sent.

Status codes

Most refusals arrive as 200 with "error": true; only a few operations answer 404. Handle both.

Authentication and permission errors

401 means Rhombus couldn't establish who is calling. 403 means it could, and that caller isn't allowed to do this. Neither succeeds if you repeat it unchanged: fix the credential, the role or the request. The one case to retry is an expired credential, after you renew it.

Missing OAuth scope. When an OAuth access token lacks the scope an operation needs, the 403 names the scope in a WWW-Authenticate header. Ask for that scope when the user signs in (Sign in with Rhombus):

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="physical"

Password-protected share links. A request to a password-protected share link without the right password gets 401 with WWW-Authenticate: Basic.

Authentication lists what to check for each kind of credential.

Request bodies

• Send POST with Content-Type: application/json and a JSON object, {} when the operation takes no parameters.
• Field names are case-sensitive, and most operations ignore fields they don't recognize. A misspelled or wrongly capitalized field is dropped without an error, so a filter that seems to have no effect is usually a spelling mistake. Copy field names from the API Reference.
• Enum values are case-sensitive. An unrecognized value is usually rejected with 400, but a few fields replace it with their default value instead, so a typo can change a setting. Send values exactly as the reference lists them.
• Timestamps are Unix epoch milliseconds in fields ending in Ms. Fields ending in Sec, Secs or Seconds are in seconds.
• Validation messages use the server's field names, which can have a leading underscore: [Error: [_targetUuid]: unexpected null value for required field] refers to targetUuid.

Retries and backoff

Retry only what can succeed unchanged:

How to wait:

• Throttling (429): the server says how long in Retry-After, for both your organization's limit and the per-camera limits on clips and frames. Wait at least that long, plus a little random jitter so many workers don't retry at the same instant. Retrying a throttled camera early makes its next wait longer.
• Temporary failures (5xx, network errors): back off exponentially with full jitter: wait a random time between 0 and min(60 s, 1 s × 2^attempt).
• Bound every retry loop with a maximum number of attempts (about 5) and a time budget, then report the failure with its status, errorCode, errorMsg and txid.
• Check before repeating a write. If a request that creates something (a clip, a key, a user) timed out or failed with a 5xx, it may still have succeeded; look for the result before sending it again, so you don't create a duplicate.
• Share the budget. Every key and token in your organization draws on the same rate limit, so many workers retrying at once still count together; spread scheduled jobs out instead of starting them all on the minute.

A client wrapper that follows these rules:

import random
import time

import requests

RETRYABLE = {429, 500, 502, 503, 504}

session = requests.Session()
session.headers.update({"x-auth-scheme": "api-token", "x-auth-apikey": "YOUR_API_KEY"})

def call(url, body, attempts=5, base=1.0, cap=60.0, budget=120.0):
    """POST to the Rhombus API, retrying throttling and temporary failures."""
    deadline = time.monotonic() + budget
    for attempt in range(attempts):
        try:
            response = session.post(url, json=body, timeout=30)
        except (requests.ConnectionError, requests.Timeout):
            response = None  # network trouble: retry like a 5xx
        if response is not None and response.status_code not in RETRYABLE:
            response.raise_for_status()  # other 4xx: fix the request, don't retry
            data = response.json()
            if data.get("error"):
                raise RuntimeError(data.get("errorMsg"))  # refused: don't retry unchanged
            return data
        if response is not None and response.status_code == 429:
            delay = float(response.headers.get("Retry-After", "1")) + random.uniform(0, 1)
        else:
            delay = random.uniform(0, min(cap, base * 2 ** attempt))
        if attempt == attempts - 1 or time.monotonic() + delay > deadline:
            break
        time.sleep(delay)
    raise RuntimeError(f"gave up after {attempt + 1} attempts: {url}")

const RETRYABLE = new Set([429, 500, 502, 503, 504]);
const headers = { "x-auth-scheme": "api-token", "x-auth-apikey": "YOUR_API_KEY", "Content-Type": "application/json" };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function call(url, body, { attempts = 5, baseMs = 1000, capMs = 60000, budgetMs = 120000 } = {}) {
  const deadline = Date.now() + budgetMs;
  for (let attempt = 0; attempt < attempts; attempt++) {
    let response;
    try {
      response = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal: AbortSignal.timeout(30000) });
    } catch {
      response = undefined; // network trouble: retry like a 5xx
    }
    if (response && !RETRYABLE.has(response.status)) {
      if (!response.ok) throw new Error(`HTTP ${response.status}`); // other 4xx: fix the request
      const data = await response.json();
      if (data.error) throw new Error(data.errorMsg); // refused: don't retry unchanged
      return data;
    }
    const delay =
      response?.status === 429
        ? Number(response.headers.get("Retry-After") ?? 1) * 1000 + Math.random() * 1000
        : Math.random() * Math.min(capMs, baseMs * 2 ** attempt);
    if (attempt === attempts - 1 || Date.now() + delay > deadline) break;
    await sleep(delay);
  }
  throw new Error(`gave up: ${url}`);
}

Contacting support

When an error persists, email support@rhombus.com with:

• The operation path and the time of the request, with its time zone.
• Your region (US or EU).
• The status code and the body, including errorCode and errorMsg.
• The request ID: txid in the error body, also sent as the x-rhombus-txid response header.

Never send your API key, OAuth tokens or federated tokens.