API

Paginación y errores

Convenciones compartidas de respuesta, envelope de error y guía de reintentos.

Todo endpoint de lista pagina del mismo modo y toda respuesta no-2xx envuelve el mismo envelope. Esta página documenta esas convenciones compartidas para que las páginas por-recurso se centren en los campos específicos del recurso.

Paginación

Los endpoints de lista usan un índice de página 1-based más un tamaño de página:

ParámetroTipoPor defectoNotas
pageinteger1Índice de página, empezando en 1.
pageSizeinteger500Número de filas por página.

La respuesta envuelve el envelope estándar {rows, pagination}:

{
  "data": {
    "rows": [
      { "id": 12, "name": "..." },
      { "id": 13, "name": "..." }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 500,
      "total": 18,
      "totalPages": 1
    }
  }
}

Para iterar por todas las filas, incrementa page hasta que page > totalPages.

Envelope de respuesta

Cada respuesta de la API — éxito y fallo por igual — envuelve su payload en un envelope estándar. En éxito, el recurso (o el envelope de lista anterior) va bajo data. En fallo, el envelope lleva el código de error, el mensaje legible y el request id.

{
  "success": false,
  "code": "APIf006",
  "message": "Field {0} exceeds the maximum length of {1} characters.",
  "data": ["username", 30],
  "request_id": "<request-id>"
}
CampoNotas
codeCódigo de error catalogado (ver abajo). Estable entre versiones.
messagePlantilla legible en inglés, con sus huecos {0}, {1}… sin rellenar. El fraseo puede evolucionar.
dataLos valores que rellenan los huecos de message (por ejemplo [fieldName, maxLength]), o un detalle del error cuando el mensaje no tiene huecos.
request_idIdentificador de correlación; también devuelto en la cabecera X-Request-Id.

Los mensajes de error son plantillas

El message de un error catalogado es el texto del catálogo tal cual, con sus huecos posicionales sin rellenar; los valores van en data, y es el cliente quien rellena el mensaje. El ejemplo anterior se lee Field username exceeds the maximum length of 30 characters.

  • data[0] rellena {0}, data[1] rellena {1}, y así sucesivamente, esté donde esté cada hueco en el texto (un mensaje puede usar {1} antes que {0}). Cuando el mensaje tiene un solo hueco, data puede ser ese valor en lugar de una lista de un elemento.
  • Trata los valores como texto: un id tomado de la ruta de la petición llega como cadena ("42").
  • Solo { + dígitos + } es un hueco. Otras llaves son texto literal — una ruta como {livestreamId} o un fragmento JSON.
  • Sustituye en una sola pasada, de modo que un valor que contenga {0} no se vuelva a expandir. Quita el hueco que no tenga valor, para que ningún {n} llegue a la persona.
  • Cuando el mensaje no tiene huecos, data es un detalle del error: un id, un nombre, un texto corto, una lista o un objeto. También puede ser null.
  • Los errores que se reenvían desde otro componente (un Encoder, por ejemplo) llevan solo su texto: data es null, y code también puede serlo.
  • Reconoce un error por su code, nunca por su message.

Catálogo de errores

La plataforma expone un catálogo de errores estable basado en prefijos. Los códigos los publica el servidor en el mismo deploy y son estables entre versiones — consulta el spec OpenAPI para la referencia exacta por operación.

PrefijoFamiliaEjemplos
SYSfSistema / genérico.SYSf001 Invalid request, SYSf014 The backend responded with an error.
SECfAutenticación, autorización y estado de cuenta.SECf004 Duplicate username, SECf005 Not logged in, SECf013 Not allowed, SECf017 Account locked.
APIfValidación, parámetros y errores de contrato.APIf001 Wrong parameters, APIf003 Field not found, APIf050 Record already exists.
APIf1xxErrores de Device / encoder.APIf100 Device not found.
APIf5xxErrores de Live stream.APIf500 Live stream configuration not found, APIf524 Max live streams reached.
APIf6xxErrores de Destination.APIf650 Destination not found, APIf651 Destination name not unique.
APIf7xxErrores de Encoding.APIf700 Encoding not found, APIf710 Encoding in use.
APIf8xxErrores de Channel.APIf800 Channel not found, APIf820 Channel in use.
CUTfEditor de grabaciones / cortes.CUTf006 No cuts done with the selected intervals.
DRMfWorkflow DRM.DRMf011 DRM provider not selected, DRMf013 Provider disabled.

Discrimina por code para manejo grueso; consulta las páginas por-recurso para los códigos que una operación dada puede producir. Los códigos heredados con prefijo en mayúsculas (APIF517, APIF519, SYSF008) siguen circulando en respuestas legacy y son equivalentes a la familia en minúsculas.

Códigos HTTP

StatusSignificado
200 OKÉxito con cuerpo.
400 Bad RequestPetición mal formada, validación, falta un campo obligatorio.
401 UnauthorizedCredenciales ausentes o inválidas (SECf005, SECf014, SECf021).
403 ForbiddenAutenticado pero no permitido (SECf013).
404 Not FoundRecurso no existe.
409 ConflictConflicto de estado o duplicado (APIf050, nombre duplicado).
422 Unprocessable EntityValidación semántica.
429 Too Many RequestsRate limit excedido. Respeta Retry-After.
500 Internal Server ErrorFallo no manejado en servidor. Reintentar.
502 Bad GatewayUpstream inalcanzable.
503 Service UnavailableServidor saturado o reiniciando.
504 Gateway TimeoutUpstream timed out.

Request id

Cada respuesta incluye X-Request-Id y replica el mismo valor en request_id en fallos. Los Operators incluyen este id en los tickets de soporte para que el equipo de plataforma pueda recuperar el log servidor correspondiente.

X-Request-Id: <request-id>

Guía de reintentos

Reintenta solo en fallos transitorios:

Status¿Reintentar?Backoff
2xxNunca.n/a
4xx (400, 401, 403, 404, 409, 422)Nunca. Arregla la petición o el estado y envía una nueva.n/a
429Sí.Respeta Retry-After. Si falta, empieza en 1 s y dobla hasta 60 s.
5xxSí.Backoff exponencial: 1 s, 2 s, 4 s, 8 s, 16 s, 32 s, tope 60 s. Para tras 6 intentos.

Cuando reintentes mutaciones, envía el mismo Idempotency-Key para que el servidor pueda deduplicar. Consulta API Overview para el contrato de idempotencia.

FAQ

Copyright © 2026