# What a response contains

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.

> **Type:** reference
> **For:** Developers who evaluate responses of the Szenera API
> **Prerequisite:** a first call whose response you have in front of you

## 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](/api/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 |

```json
{
  "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).

## Related

- [The error format](/api/error-format)
- [Paging](/api/pagination)
- [Concurrent changes: ETag and If-Match](/api/etag-and-if-match)