Errores y códigos de estado

La API REST informa una solicitud fallida de una de dos formas, así que revisa ambas:

1. Un código de estado HTTP de error cuando la solicitud no se puede procesar: JSON mal formado, un campo que falta, un problema con la credencial, un permiso denegado o un límite de tasa. El cuerpo tiene "error": true y un errorCode legible por máquina.
2. HTTP 200 con "error": true cuando la solicitud era válida pero la acción falló o se rechazó, por ejemplo un rol que no puedes asignar. El motivo está en errorMsg:

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

Una solicitud tuvo éxito solo cuando el estado es 2xx y error es false.

El sobre de la respuesta

Cada respuesta JSON de la API REST incluye los mismos tres campos junto a sus datos:

Las respuestas de error tienen el mismo cuerpo en todos los hosts: la API REST, los hosts de medios, los handshakes de WebSocket y el servidor MCP.

Cada respuesta de error incluye errorCode, un código estable para decidir qué hacer, junto a errorMsg, un mensaje para mostrar o registrar. Los códigos nunca se renombran ni se eliminan, pero se agregan nuevos: maneja un código que no reconozcas según su estado HTTP.

Toda respuesta con un estado de error tiene el mismo cuerpo. msg es la frase de motivo HTTP, que se conserva para clientes antiguos; status repite el estado HTTP; timestamp es el momento del error, en milisegundos de época Unix; txid es el ID de la solicitud que debes indicar al soporte, también enviado como encabezado x-rhombus-txid:

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

Los códigos que devuelve la API hoy (los significados están en inglés):

Los campos con valor nulo se omiten en las respuestas, así que trata un campo ausente como nulo. Las listas vacías sí se envían.

Códigos de estado

La mayoría de los rechazos llegan como 200 con "error": true; solo algunas operaciones responden 404. Maneja ambos casos.

Errores de autenticación y de permisos

401 significa que Rhombus no pudo establecer quién llama. 403 significa que sí pudo, y que ese llamador no tiene permiso para hacer esto. Ninguno tiene éxito si lo repites sin cambios: corrige la credencial, el rol o la solicitud. El único caso que se reintenta es una credencial vencida, después de renovarla.

Scope de OAuth faltante. Cuando a un token de acceso OAuth le falta el scope que necesita una operación, el 403 nombra el scope en un encabezado WWW-Authenticate. Pide ese scope cuando el usuario inicia sesión (Iniciar sesión con Rhombus):

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

Enlaces compartidos protegidos con contraseña. Una solicitud a un enlace compartido protegido con contraseña sin la contraseña correcta recibe 401 con WWW-Authenticate: Basic.

Autenticación indica qué revisar para cada tipo de credencial.

Cuerpos de solicitud

• Envía POST con Content-Type: application/json y un objeto JSON, {} cuando la operación no recibe parámetros.
• Los nombres de campo distinguen mayúsculas y minúsculas, y la mayoría de las operaciones ignoran los campos que no reconocen. Un campo mal escrito o con mayúsculas incorrectas se descarta sin error, así que un filtro que parece no tener efecto suele ser un error de escritura. Copia los nombres de campo de la referencia de la API (en inglés).
• Los valores de enum distinguen mayúsculas y minúsculas. Un valor no reconocido normalmente se rechaza con 400, pero algunos campos lo sustituyen por su valor predeterminado, así que un error de escritura puede cambiar una configuración. Envía los valores exactamente como los lista la referencia.
• Las marcas de tiempo son milisegundos de época Unix en los campos que terminan en Ms. Los campos que terminan en Sec, Secs o Seconds están en segundos.
• Los mensajes de validación usan los nombres de campo del servidor, que pueden llevar un guion bajo inicial: [Error: [_targetUuid]: unexpected null value for required field] se refiere a targetUuid.

Reintentos y espera exponencial

Reintenta solo lo que puede tener éxito sin cambios:

Cómo esperar:

• Limitación (429): el servidor indica cuánto esperar en Retry-After, tanto para el límite de tu organización como para los límites por cámara de clips y fotogramas. Espera al menos ese tiempo, más un poco de jitter aleatorio para que muchos procesos no reintenten en el mismo instante. Reintentar antes de tiempo con una cámara limitada alarga su siguiente espera.
• Fallos temporales (5xx, errores de red): espera de forma exponencial con jitter completo: un tiempo aleatorio entre 0 y min(60 s, 1 s × 2^intento).
• Limita cada ciclo de reintentos con un número máximo de intentos (unos 5) y un presupuesto de tiempo, y después informa el fallo con su estado, errorCode, errorMsg y txid.
• Comprueba antes de repetir una escritura. Si una solicitud que crea algo (un clip, una clave, un usuario) agotó el tiempo o falló con un 5xx, puede haber tenido éxito igualmente; busca el resultado antes de enviarla de nuevo para no crear un duplicado.
• Comparte el presupuesto. Todas las claves y tokens de tu organización consumen el mismo límite de tasa, así que muchos procesos reintentando a la vez cuentan juntos; reparte las tareas programadas en lugar de iniciarlas todas en el mismo minuto.

Un cliente que sigue estas reglas:

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}`);
}

Contactar al soporte

Cuando un error persiste, escribe a support@rhombus.com con:

• La ruta de la operación y la hora de la solicitud, con su zona horaria.
• Tu región (EE. UU. o UE).
• El código de estado y el cuerpo, incluidos errorCode y errorMsg.
• El ID de la solicitud: txid en el cuerpo del error, que también se envía como encabezado de respuesta x-rhombus-txid.

Nunca envíes tu clave de API, tus tokens OAuth ni tus tokens federados.