# Error codes: devices, playback, notifications, operations

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.

> **Type:** reference
> **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](/api/error-format)

## 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](/webhooks/troubleshooting). `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.

## Related

- [The error format](/api/error-format)
- [When no delivery arrives](/webhooks/troubleshooting)