What a response contains
Status, headers, list shape, IDs with a prefix, and the error body: everything a response of the API holds, in tables.
5 minute readGetting startedUpdated: 10/25/2026
On this page
Before you start
- For
- Developers who evaluate responses of the Szenera API
- Prerequisite
- a first call whose response you have in front of you
This page is a lookup table: find what you encounter in a response (a status, header, list field, ID, or error field) in the tables, and read next to it what it means.
Status classes
| Status | Meaning | What you do |
|---|---|---|
200, 201 |
Success. 201 when a resource is created. |
Evaluate the body. |
302 |
Only on the sign-in flows through a provider, on cloud connections (round trip through the browser), and when fetching an app bundle (redirect to storage). | Not relevant for ordinary calls with a key. curl follows with -L. |
4xx |
Your call: credential, permission, path, body, or state do not fit. Always with an error body. | Evaluate code, correct the call. |
5xx |
The platform or a downstream service (502). Also with an error body. |
Report the traceId. For 502 with Retry-After, retry later. |
Headers
Except for Idempotent-Replay, all headers named here are also readable for browser clients on a different origin.
| Header | When | Meaning |
|---|---|---|
Content-Type |
always | application/json. With Accept: application/problem+json, errors come as application/problem+json |
X-Trace-Id |
always | Trace ID of this call, trc_…, identical to traceId in the error body |
X-Correlation-Id |
if the call carries a correlation ID | ID of a related operation, cor_… |
ETag |
on the read and change routes of versioned resources (scenes, playlists, programs, roles, displays) | the version of the resource as a tag, such as "7". When changing, send it back as If-Match (see Concurrent changes: ETag and If-Match) |
Idempotent-Replay |
on a retry with the same Idempotency-Key |
true: the stored response was delivered, and the action did not run again |
X-RateLimit-Limit |
only on throttled routes | requests allowed in the window |
X-RateLimit-Remaining |
only on throttled routes | of those, still available |
X-RateLimit-Reset |
only on throttled routes | start of the next window in Unix seconds |
Retry-After |
on 429 and on 502 with a wait time |
seconds until the next permitted attempt |
Server-Timing |
if the platform includes timing measurements | duration of processing on the server |
Lists
Paged lists always have the same shape:
| Field | Meaning |
|---|---|
items |
the records of this page |
nextCursor |
the marker for the next page, absent on the last page |
total |
the total count where the route knows it, otherwise the field is absent |
You page with the query parameters limit (page size) and cursor (value of nextCursor). For paged lists, limit ranges from 1 to 200 with a default of 50. The filtered administration lists (devices, accounts, roles, keys) cap at 100 with a default of 25. Small lists that cannot be paged answer with a plain list, and the shape is stated at the endpoint in the reference.
Identifiers
Every ID consists of a prefix and 26 characters in the Crockford Base32 alphabet (digits and capital letters without I, L, O, and U), for example scn_01KJPX8NH0SZENE00000000001. The prefix says what the ID denotes:
| Prefix | Denotes |
|---|---|
tnt_ |
Organization |
usr_ |
User account |
dev_ |
Device |
ply_ |
Display (playerId in the API) |
scn_ |
Scene |
pll_ |
Playlist |
sch_ |
Program (in the API scheduleId) |
ast_ |
Media item |
fld_ |
Media folder |
rol_ |
Role |
whk_ |
Webhook endpoint |
whd_ |
Webhook delivery |
akm_ |
API key (the entry in lists) |
adv_ |
Advertiser |
acp_ |
Ad campaign |
bkl_ |
Booking of an ad campaign |
crv_ |
Creative of a booking |
ppr_ |
Plan revision of a display |
pss_ |
Screenshot of a display |
pbt_ |
Batch of plays that a device has reported |
pcl_ |
Closing of a booking over a period |
prf_ |
Proof of a closing |
pfi_ |
File of a proof (PDF, log, manifest, screenshot) |
pdy_ |
Delivery of a proof to a contact of the advertiser |
shl_ |
Link with which an advertiser opens their proofs without an account |
rvs_ |
Revenue statement of a location for a month |
trc_ |
Trace ID of a call |
cor_ |
Correlation ID of an operation |
The key itself begins with ak_ and is a secret value: it appears only once, when it is issued. Lists show its ID akm_… and the prefix ak_ plus nine characters for recognition.
Error body
| Field | When | Meaning |
|---|---|---|
code |
always | stable code in the form Area.Cause, such as Auth.Required or Conflict.OptimisticLock. Branch on this |
message |
always | short text for humans. Do not parse it |
traceId |
always, never empty | trace ID trc_… for follow-up questions |
details |
if the error carries additional information | such as issues for Validation.Failed, expected/actual for Conflict.OptimisticLock. Absent otherwise |
correlationId |
if the call carries a correlation ID | cor_… |
retryAfterSeconds, externalService |
only for integration errors (502) |
wait time (also as Retry-After) and the downstream service concerned |
stack |
never in production | only in development environments for internal errors |
{
"code": "Scene.NotFound",
"message": "Resource not found",
"traceId": "trc_01KXWFT3H0SPR0000000000001"
}
The HTTP status follows the area of the code: Validation.* → 422, Auth.* → 401, Permission.* → 403, *.NotFound → 404, Conflict.* → 409, RateLimit.* → 429, Payload.* → 413, Integration.* → 502. Individual codes deviate explicitly, and the error code pages name the status actually sent for each code.
Errors as Problem Details (RFC 9457)
Send Accept: application/problem+json, and the same error comes as a ProblemDetails document:
| Field | When | Meaning |
|---|---|---|
type |
always | address form of the code, lowercase with slashes |
title |
always | short title of the code |
status |
always | the HTTP status |
detail |
always | the text of message |
code |
always | the same code as in the standard body |
instance |
depending on the case | the requested path |
errorDetails |
depending on the case | the same additional information as details |
traceId, correlationId, retryAfterSeconds |
depending on the case | as above |
There is never a stack in this form.
Timestamps
All timestamps are strings in ISO 8601 with a time zone offset, for example "createdAt": "2026-05-04T07:00:00.000Z". A missing timestamp appears as null (such as "expiresAt": null for a key with no expiry).