Skip to content
Szenera DeveloperDocs
API › Error codes › Error codes: devices, playback, notifications, operations
Chapters

Error codes: devices, playback, notifications, operations

The codes of the areas Fleet, Playback, Realtime, Notifications, Analytics, Audit, and Ops-Console, the latter only on operator routes.

14 minute readAPIUpdated: 10/25/2026

On this page

Before you start

For
Anyone who controls devices and displays, runs webhooks, retrieves analytics, or reads the audit log.
Prerequisite
know the error format — see The error format

The codes of the Fleet, Playback, Realtime, Notifications, Analytics, and Audit areas, and those of the operations console, which arise only on platform-operations routes.

How to read the tables

Read the tables like this: Code is the value of the code field in the error body. Your logic switches on it, never on message. Meaning and Typical trigger classify the case. HTTP is the status actually sent. Expected reaction is your client’s response, drawn from a fixed vocabulary that is the same on all seven error-code pages: “check credentials” (401), “check permission or package” (402, 403), “correct the input” (400, 413, 415, 422), “reload, resend” (version conflicts), “do not retry, check the operation” (404, 409, 410, 426), “wait (Retry-After)” (429), and “retry later, report the trace ID if it recurs” (5xx).

The codes

Devices and displays (Fleet)

Displays, pairing, commands, tags, video walls, locations, and updates. Device.NotPaired (409) is a state that passes on its own: the device is registered but not yet assigned to an organization.

Code Meaning Typical trigger HTTP Expected reaction
Device.NotPaired Device not yet assigned to an organization Self-report of a freshly registered agent (capabilities, events, screenshots) before anyone has redeemed the pairing code in the portal. A code of its own, because as Player.NotFound this preliminary phase could not be told apart from an outage — it passes on its own 409 do not retry, check the operation
Player.NotFound Display not found Unknown display ID 404 do not retry, check the operation
Player.AlreadyDecommissioned Display already removed Action on a removed display, including a second removal 409 do not retry, check the operation
Player.ConfigInvalid Display configuration invalid Malformed configuration 422 correct the input
Player.OutputNotAvailable No reported connector at this position “Add display” on an output that the device has not reported as occupied (cable missing, or the capability report is still pending) 409 do not retry, check the operation
Player.ScreenIndexTaken Position already occupied “Add display” on a connector that already has a display attached 409 do not retry, check the operation
Player.ScreenshotNotFound No screenshot stored Fetching the screenshot as bytes for a display that has not sent one yet or whose screenshot has been cleaned up 404 request a screenshot first, then retry
Player.KeepDeviceNotAllowed Device without a display not intended DELETE /v1/players/:id?device=keep on the last display of a device, without the multiDisplayPerDevice capability 422 correct the input
Pairing.SessionNotFound Pairing session not found Unknown pairing session 404 do not retry, check the operation
Pairing.CodeInvalid Pairing code invalid Wrong 6-character code 404 do not retry, check the operation
Pairing.CodeExpired Pairing code expired Expired code 410 do not retry, check the operation
Pairing.SessionAlreadyClaimed Pairing already claimed Duplicate pairing 409 do not retry, check the operation
Command.NotFound Command not found Unknown command ID 404 do not retry, check the operation
Command.InvalidPayload Command data invalid Malformed command data 422 correct the input
Command.InvalidTransition Invalid command transition Disallowed status change 409 do not retry, check the operation
Command.OutputNotAvailable Command without stored output Fetching the output artifact (screenshot, log) of an existing command: never executed, the result came inline, or the upload is still pending. A code of its own, otherwise the case could not be told apart from an unknown command 404 do not retry, check the operation
Command.NotSupportedByDevice Command does not fit the device Restart sent to a display without an agent. display-power sent to a panel that did not answer the CEC probe (here missing knowledge is, exceptionally, a rejection — a switch that does nothing is worse than a missing one) 422 correct the input
Command.WrongScope Command type on the wrong target Restart through the display route or screenshot through the device route. The response names the correct route. It used to be accepted silently, and then a restart blacked out the second display of the same device without warning 422 correct the input
PlayerTag.NotFound Tag not found Unknown tag ID 404 do not retry, check the operation
PlayerTag.NameAlreadyExists Tag name taken Duplicate tag name 409 do not retry, check the operation
DisplayGroup.NotFound Video wall not found Unknown video wall ID 404 do not retry, check the operation
DisplayGroup.NameAlreadyExists Video wall name taken Duplicate name in the organization 409 do not retry, check the operation
DisplayGroup.RectOutOfCanvas Layout yields no surface A rectangle extends beyond the surface, a display appears twice, or there is no member 422 correct the input
Player.AlreadyInDisplayGroup Display already on a surface Creating or rebuilding with a display that already belongs to another video wall 409 do not retry, check the operation
Location.NotFound Location not found An ID that belongs to no location of this organization 404 do not retry, check the operation
Location.NameAlreadyExists Location name taken Creation or renaming to a name that already exists in the organization 409 do not retry, check the operation
Location.HasPlayers Location is occupied Deleting a location where displays are still attached. The response gives their count 409 do not retry, check the operation
WebDisplay.NotABrowserDisplay Not a display without a device Deleting or requesting a new connect address through /v1/web-displays where the ID belongs to a display with a device. Neither a permission nor an ID problem, but the wrong door: for a device there are DELETE /v1/players/{id} and POST /v1/devices/{id}/reconnect-link 409 do not retry, check the operation
Ota.AlreadyInProgress Update already active Second update at the same time 409 do not retry, check the operation
Ota.InvalidTransition Invalid update transition Disallowed status change of the update 409 do not retry, check the operation
Timeline.WindowOutOfRange Timeline window outside the span Query that reaches too far into the past or future. Looking back is not the purpose of the timeline, and beyond the look-ahead limit every resolution would assume unchanged schedules. The limit depends on the clock, so it is checked at evaluation and not in the query schema 422 correct the input
PlaybackHistory.DateOutOfRange Day outside the recording Future or older than 90 days 422 correct the input

Playback

Playback packages and the reports of the display software.

Code Meaning Typical trigger HTTP Expected reaction
Snapshot.NotFound Playback package not found Unknown playback package of a display 404 do not retry, check the operation
Renderer.DiagnosticsRateLimited Diagnostics rate exceeded Diagnostic reports sent too often 429 wait (Retry-After)

Real-time connections (Realtime)

Only Connection.NotFound occurs regularly as an HTTP error. The other four codes are reasons for rejecting the real-time connection, without an error body. The HTTP column gives their equivalent in case they do reach an HTTP path. The real-time connection cannot be reached with an API key.

Code Meaning Typical trigger HTTP Expected reaction
Connection.AuthFailed Sign-in of the connection failed Opening the real-time connection without a valid credential 401 check credentials
Connection.NotFound Connection not found Unknown connection ID 404 do not retry, check the operation
Connection.RateLimited Connection rate exceeded Too many connection attempts 429 wait (Retry-After)
Subscription.PermissionDenied Permission for the topic missing No access to the topic 403 check permission or package
Topic.InvalidFormat Topic format invalid Malformed topic name 422 correct the input

Notifications and webhooks (Notifications)

Inbox, delivery channels, email, and webhooks. The five webhook codes concern the management of endpoints: WebhookEndpoint.NotFound (404), WebhookEndpoint.Disabled (409), WebhookEndpoint.UrlInvalid (422), WebhookEndpoint.EventUnknown (422), and WebhookDelivery.NotFound (404). What to do when deliveries fail to arrive is described under When no delivery arrives. Email.ProviderUnavailable is a deliberate 502 among the domain codes.

Code Meaning Typical trigger HTTP Expected reaction
Notification.NotFound Notification not found Unknown notification ID 404 do not retry, check the operation
Preferences.InvalidChannel Invalid channel Unknown notification channel 422 correct the input
WebhookEndpoint.NotFound Webhook endpoint not found Unknown endpoint ID 404 do not retry, check the operation
WebhookEndpoint.Disabled Webhook endpoint disabled Use of a disabled endpoint 409 do not retry, check the operation
WebhookEndpoint.UrlInvalid Webhook URL invalid Malformed target URL 422 correct the input
WebhookEndpoint.EventUnknown Event type unknown An entry in events is not in the event catalog and does not have the form <area>.* or * either. The response lists the unknown names under details.unknownEvents 422 correct the input
WebhookDelivery.NotFound Delivery not found Unknown delivery ID 404 do not retry, check the operation
Email.ProviderUnavailable Email provider unreachable Outage of the mail delivery 502 retry later, report the trace ID if it recurs
Email.TemplateNotFound Email template not found Unknown template 404 do not retry, check the operation

Analytics

Reports and queries. Dimension.Unknown replaces a silent empty result: the detail names the permitted axes. The ad hoc analysis checks every query against the metric catalog: AnalyticsQuery.NotAllowed names in details.reason the same reason that GET /v1/analytics/catalog returns for each combination of metric and dimension. An expired or revoked link answers with 410 and not with 404: The link existed, it just no longer applies.

Code Meaning Typical trigger HTTP Expected reaction
AnalyticsReport.NotFound Report not found Unknown report ID 404 do not retry, check the operation
GeneratedReport.NotFound Generated report not found Unknown report run 404 do not retry, check the operation
GeneratedReport.Expired Generated report expired Expired download 410 do not retry, check the operation
AnalyticsQuery.Invalid Query invalid Malformed analytics query 422 correct the input
Metric.Unknown Metric unknown The metric does not exist 422 correct the input
Dimension.Unknown Axis does not carry the metric Breakdown by a dimension that the metric catalog does not list for this metric. The code replaces silent emptiness: before, an empty result came back without any hint. The detail names the permitted axes 422 correct the input
AnalyticsQuery.CardinalityExceeded Too many value combinations Query with too many axes 422 correct the input
AnalyticsQuery.NotAllowed Combination not allowed A metric and dimension or filter that the metric catalog does not calculate together, for example fulfillment without restriction to an ad campaign 422 adjust the query according to details.reason
AnalyticsQuery.WindowInvalid Time window invalid Window empty, reversed, or longer than a query can cover 422 correct the input
AnalyticsQuery.PerspectiveDenied Perspective not allowed A perspective that the caller is not entitled to, for example the network perspective for an organization 403 check permission or package
AnalyticsCampaign.NotFound Ad campaign not found Unknown ad campaign or an ad campaign owned by someone else 404 do not retry, check the operation
Proof.NotFound Proof not found Unknown proof ID, a proof owned by someone else, or one that the link does not cover 404 do not retry, check the operation
ProofFile.NotFound File not found This proof has no file of that kind, the screenshot does not belong to it, or its files are still being created 404 reload the list of files, try again later
Proof.BookingLineNotFound Booking not found Interim statement for an unknown booking or a booking owned by someone else 404 do not retry, check the operation
Proof.InterimWindowInvalid Period of the interim statement invalid Period reversed, outside the run of the booking, or beyond yesterday 422 adjust the period according to details.reason
Proof.AdvertiserNotFound Advertiser not found Link for an unknown advertiser or one owned by someone else 404 do not retry, check the operation
ProofShareLink.NotFound Link not found Unknown key or a link ID owned by someone else 404 do not retry, check the address
ProofShareLink.Expired Link expired The link has passed its expiry date 410 do not retry, request a new link
ProofShareLink.Revoked Link revoked The organization or the operator has withdrawn the link 410 do not retry, request a new link

Audit log (Audit)

Log entries, exports, and pseudonymization from the organization’s point of view.

Code Meaning Typical trigger HTTP Expected reaction
AuditEntry.NotFound Log entry not found Unknown entry ID 404 do not retry, check the operation
AuditExport.NotFound Log export not found Unknown export ID 404 do not retry, check the operation
AuditExport.NotReady Log export not ready Download before completion 409 do not retry, check the operation
Audit.CrossTenantForbidden Cross-organization access forbidden Access to the audit log of another organization 403 check permission or package
Pseudonymization.ReasonRequired Reason required Pseudonymization without a reason (≥20 characters) 422 correct the input
Pseudonymization.JobNotFound Pseudonymization job missing Unknown job ID 404 do not retry, check the operation
Pseudonym.NotFound Pseudonym not found Lookup without a match 404 do not retry, check the operation

Operations console (Ops-Console)

These codes arise exclusively on platform-operations routes: the device software including the channel of a device, maintenance windows, and incidents. A key of an organization cannot reach these routes. The table is here for completeness.

Code Meaning Typical trigger HTTP Expected reaction
DeviceSoftware.ComponentNotSupported Component without a delivery path Fetching, releasing, or delivering a component that this version of the platform does not deliver yet. Today that is everything except the display software 422 correct the input
DeviceSoftware.BuildNotFound Build not in storage Releasing a build that the environment has not yet fetched from the registry 404 do not retry, check the operation
DeviceSoftware.ArtifactNotFound Archive not in storage Fetching an archive with an unknown component, build, or name 404 do not retry, check the operation
DeviceSoftware.RegistryArtifactNotFound Build not in the registry The tag does not (or no longer) exist in the registry 404 do not retry, check the operation
DeviceSoftware.RegistryImportFailed Fetching from the registry failed Access missing, the manifest is incomplete, a checksum differs, a profile is missing, or the description in the archive contradicts the manifest. The detail names the cause 422 correct the input
DeviceSoftware.NotReleasable Build cannot be released The build requires a version of the interface that the environment does not speak, or a profile or archive is missing 422 correct the input
DeviceSoftware.SigningKeyNotConfigured No signing key The environment has no key with which it signs releases. Without a signature, no device accepts a release 422 correct the input
DeviceSoftware.EnvironmentNotConfigured World unknown The environment does not know its world, and a release without a world could not be assigned to any device 422 correct the input
DeviceSoftware.BuildNotReady Build not ready Releasing a SzeneraOS build whose bundle is still being fetched from the registry and checked 409 do not retry, check the operation
DeviceSoftware.VersionAlreadyExists Version already taken Importing a SzeneraOS bundle whose version is already in storage under a different build 409 do not retry, check the operation
DeviceSoftware.WorldMismatch Bundle built for a different world The world of the bundle differs from the world of this server (PLATTFORM_WELT), checked on import 422 correct the input
DeviceSoftware.ReleaseNotFound Release not found Nudging a release that does not exist for this component 404 do not retry, check the operation
DeviceSoftware.ReleaseNotCurrent Release no longer current Nudging a release that a newer one has replaced in the channel 409 do not retry, check the operation
DeviceSoftware.ImageNotFound No image in the registry Fetching the image for a SzeneraOS version for which the registry holds none 404 do not retry, check the operation
DeviceSoftware.BuildDeleted Build deleted Releasing a build whose bytes are deleted. The record stays as a tombstone 409 do not retry, check the operation
DeviceSoftware.BuildInUse Build cannot be deleted Deleting a build that is current in a channel or that an open request points to 409 do not retry, check the operation
DeviceSoftware.PullAlongInvalid Channel cannot be pulled along pullAlong names a channel that is not lower than the target or that the package does not carry 422 correct the input
ReleaseApproval.NotFound Request not found Unknown ID of a request to a second person 404 do not retry, check the operation
ReleaseApproval.AlreadyOpen Request already waiting A request for the same target and the same operation is already waiting 409 do not retry, check the operation
ReleaseApproval.NotOpen Request no longer waiting Approving or withdrawing a request that has been approved, withdrawn, or has expired after seven days. details.state names the state 409 do not retry, check the operation
ReleaseApproval.SamePerson Only a second person can approve The person who made the request wants to approve it themselves 403 check permission or package
ReleaseApproval.NotPermitted Rejecting not permitted A person without the permission to approve wants to reject someone else’s request 403 check permission or package
ReleaseApproval.ReasonRequired Reason missing The platform requires a second person for a release to stable, and the call names no reason (reason) 422 correct the input
Device.ChannelNotApplicable No channel for this display Setting the channel on a web display or on another display without remote maintenance. It has no channel and always gets the display software from stable 409 do not retry, check the operation
Device.ChannelNotFollowed Remote maintenance does not read the channel yet Setting the channel on a device whose remote maintenance still follows the channel of its setup file. A value set would exist only in the portal. The rejection goes away with the next remote-maintenance package 409 do not retry, check the operation
MaintenanceWindow.NotFound Maintenance window not found Unknown window ID 404 do not retry, check the operation
MaintenanceWindow.InvalidSchedule Maintenance window time invalid Malformed time details 422 correct the input
IncidentRecord.NotFound Incident not found Unknown incident ID 404 do not retry, check the operation

Count

This page lists 102 codes. Together with the other six error-code pages this gives 493 domain codes (4xx) and 119 server errors (5xx), 612 codes in all — the complete catalog of the platform.