API

Pagination and Errors

Shared response conventions, error envelope and retry guidance.

Every list endpoint paginates the same way and every non-2xx response wraps the same envelope. This page documents those shared conventions so per-resource pages can stay focused on resource-specific fields.

Pagination

List endpoints use a 1-based page index plus a page size:

ParameterTypeDefaultNotes
pageinteger1Page index, starting at 1.
pageSizeinteger500Number of rows per page.

The response is wrapped in the standard {rows, pagination} envelope:

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

To iterate through every row, increment page until page > totalPages.

Response envelope

Every API response — success and failure alike — wraps its payload in a standard envelope. On success, the resource (or list envelope above) is placed under data. On failure, the envelope carries the error code, the human-readable message and the request id.

{
  "success": false,
  "code": "APIf006",
  "message": "Field {0} exceeds the maximum length of {1} characters.",
  "data": ["username", 30],
  "request_id": "<request-id>"
}
FieldNotes
codeCatalogued error code (see below). Stable across releases.
messageHuman-readable English template, with its {0}, {1}… placeholders left in place. Phrasing may evolve.
dataThe values that fill the placeholders of message (for example [fieldName, maxLength]), or a detail of the error when the message has none.
request_idCorrelation identifier; also echoed in the X-Request-Id response header.

Error messages are templates

The message of a catalogued error is the catalogue text as written, with its positional placeholders left in place; the values travel in data, and the client fills the message. The example above reads Field username exceeds the maximum length of 30 characters.

  • data[0] fills {0}, data[1] fills {1}, and so on, wherever each placeholder stands in the text (a message may use {1} before {0}). When the message has a single placeholder, data may be that one value instead of a one-item list.
  • Treat the values as text: an id taken from the request path arrives as a string ("42").
  • Only { + digits + } is a placeholder. Other braces are literal text — a path such as {livestreamId} or a JSON fragment.
  • Substitute in a single pass, so a value that itself contains {0} is never expanded again. Remove a placeholder that has no value, so that no {n} reaches the person.
  • When the message has no placeholder, data is a detail of the error: an id, a name, a short text, a list or an object. It may also be null.
  • Errors relayed from another component (an Encoder, for instance) carry only their text: data is null, and code may be null too.
  • Identify an error by its code, never by its message.

Error catalogue

The platform exposes a stable, prefix-based error catalogue. Codes are emitted by the server in the same deployment and are stable across releases — consult the OpenAPI spec for the exact per-operation reference.

PrefixFamilyExamples
SYSfSystem / generic.SYSf001 Invalid request, SYSf014 The backend responded with an error.
SECfAuthentication, authorisation and account state.SECf004 Duplicate username, SECf005 Not logged in, SECf013 Not allowed, SECf017 Account locked.
APIfValidation, parameter and contract errors.APIf001 Wrong parameters, APIf003 Field not found, APIf050 Record already exists.
APIf1xxDevice / encoder errors.APIf100 Device not found.
APIf5xxLive stream errors.APIf500 Live stream configuration not found, APIf524 Max live streams reached.
APIf6xxDestination errors.APIf650 Destination not found, APIf651 Destination name not unique.
APIf7xxEncoding errors.APIf700 Encoding not found, APIf710 Encoding in use.
APIf8xxChannel errors.APIf800 Channel not found, APIf820 Channel in use.
CUTfRecordings editor / cuts.CUTf006 No cuts done with the selected intervals.
DRMfDRM workflow.DRMf011 DRM provider not selected, DRMf013 Provider disabled.

Branch on the code for coarse handling; consult per-resource pages for the codes a given operation can produce. Legacy uppercase variants (APIF517, APIF519, SYSF008) still appear in older payloads and are equivalent to the lowercase family.

HTTP status codes

StatusMeaning
200 OKSuccess with body.
400 Bad RequestMalformed request, validation error, missing required field.
401 UnauthorizedMissing or invalid credentials (SECf005, SECf014, SECf021).
403 ForbiddenAuthenticated but not permitted (SECf013).
404 Not FoundResource does not exist.
409 ConflictState conflict or duplicate (APIf050, duplicate name).
422 Unprocessable EntitySemantic validation error.
429 Too Many RequestsRate limit exceeded. Honor Retry-After.
500 Internal Server ErrorUnhandled server fault. Retriable.
502 Bad GatewayUpstream unreachable.
503 Service UnavailableServer overloaded or restarting.
504 Gateway TimeoutUpstream timed out.

Request id

Every response includes X-Request-Id and echoes the same value in request_id on failure. Operators include this id in support tickets so the platform team can pull the matching server-side log.

X-Request-Id: <request-id>

Retry guidance

Retry only on transient failures:

StatusRetry?Backoff
2xxNever.n/a
4xx (400, 401, 403, 404, 409, 422)Never. Fix the request or the state, then send a new one.n/a
429Yes.Honour Retry-After. If absent, start at 1 s and double up to 60 s.
5xxYes.Exponential backoff: 1 s, 2 s, 4 s, 8 s, 16 s, 32 s, capped at 60 s. Stop after 6 attempts.

When retrying mutations, send the same Idempotency-Key so the server can deduplicate. See API Overview for the idempotency contract.

FAQ

Copyright © 2026