Paginación y errores
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ámetro | Tipo | Por defecto | Notas |
|---|---|---|---|
page | integer | 1 | Índice de página, empezando en 1. |
pageSize | integer | 500 | Nú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>"
}
| Campo | Notas |
|---|---|
code | Código de error catalogado (ver abajo). Estable entre versiones. |
message | Plantilla legible en inglés, con sus huecos {0}, {1}… sin rellenar. El fraseo puede evolucionar. |
data | Los valores que rellenan los huecos de message (por ejemplo [fieldName, maxLength]), o un detalle del error cuando el mensaje no tiene huecos. |
request_id | Identificador 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,datapuede 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,
dataes un detalle del error: un id, un nombre, un texto corto, una lista o un objeto. También puede sernull. - Los errores que se reenvían desde otro componente (un Encoder, por ejemplo) llevan solo su texto:
dataesnull, ycodetambién puede serlo. - Reconoce un error por su
code, nunca por sumessage.
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.
| Prefijo | Familia | Ejemplos |
|---|---|---|
SYSf | Sistema / genérico. | SYSf001 Invalid request, SYSf014 The backend responded with an error. |
SECf | Autenticación, autorización y estado de cuenta. | SECf004 Duplicate username, SECf005 Not logged in, SECf013 Not allowed, SECf017 Account locked. |
APIf | Validación, parámetros y errores de contrato. | APIf001 Wrong parameters, APIf003 Field not found, APIf050 Record already exists. |
APIf1xx | Errores de Device / encoder. | APIf100 Device not found. |
APIf5xx | Errores de Live stream. | APIf500 Live stream configuration not found, APIf524 Max live streams reached. |
APIf6xx | Errores de Destination. | APIf650 Destination not found, APIf651 Destination name not unique. |
APIf7xx | Errores de Encoding. | APIf700 Encoding not found, APIf710 Encoding in use. |
APIf8xx | Errores de Channel. | APIf800 Channel not found, APIf820 Channel in use. |
CUTf | Editor de grabaciones / cortes. | CUTf006 No cuts done with the selected intervals. |
DRMf | Workflow 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
| Status | Significado |
|---|---|
200 OK | Éxito con cuerpo. |
400 Bad Request | Petición mal formada, validación, falta un campo obligatorio. |
401 Unauthorized | Credenciales ausentes o inválidas (SECf005, SECf014, SECf021). |
403 Forbidden | Autenticado pero no permitido (SECf013). |
404 Not Found | Recurso no existe. |
409 Conflict | Conflicto de estado o duplicado (APIf050, nombre duplicado). |
422 Unprocessable Entity | Validación semántica. |
429 Too Many Requests | Rate limit excedido. Respeta Retry-After. |
500 Internal Server Error | Fallo no manejado en servidor. Reintentar. |
502 Bad Gateway | Upstream inalcanzable. |
503 Service Unavailable | Servidor saturado o reiniciando. |
504 Gateway Timeout | Upstream 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 |
|---|---|---|
2xx | Nunca. | n/a |
4xx (400, 401, 403, 404, 409, 422) | Nunca. Arregla la petición o el estado y envía una nueva. | n/a |
429 | Sí. | Respeta Retry-After. Si falta, empieza en 1 s y dobla hasta 60 s. |
5xx | Sí. | 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
data.rows; los que iteran leen también data.pagination.data. Discrimina por code para manejo grueso y por data para vías de recuperación específicas.