# Was eine Antwort enthält

Diese Seite ist eine Nachschlagetafel: Suchen Sie in der Tabelle, was Ihnen in einer Antwort begegnet — Status, Kopfzeile, Listenfeld, Kennung oder Fehlerfeld —, und lesen Sie daneben, was es bedeutet.

> **Typ:** nachschlagen
> **Für wen:** Entwicklerinnen und Entwickler, die Antworten der Szenera-API auswerten
> **Voraussetzung:** ein erster Aufruf, dessen Antwort Sie vor sich haben

## Statusklassen

| Status | Bedeutung | Was Sie tun |
|---|---|---|
| `200`, `201` | Erfolg; `201` beim Anlegen einer Ressource. | Rumpf auswerten. |
| `302` | Nur auf den Anmeldewegen über einen Anbieter, bei Cloud-Anbindungen (Rundlauf durch den Browser) und beim Abholen eines App-Bündels (Weiterleitung zur Ablage). | Für gewöhnliche Aufrufe mit Schlüssel nicht relevant; curl folgt mit `-L`. |
| `4xx` | Ihr Aufruf: Ausweis, Recht, Pfad, Rumpf oder Zustand passen nicht. Immer mit Fehlerrumpf. | `code` auswerten, Aufruf korrigieren. |
| `5xx` | Die Plattform oder ein nachgelagerter Dienst (`502`). Ebenfalls mit Fehlerrumpf. | `traceId` melden; bei `502` mit `Retry-After` später wiederholen. |

## Kopfzeilen

Bis auf `Idempotent-Replay` sind alle hier genannten Kopfzeilen auch für Browser-Clients auf einem anderen Ursprung lesbar.

| Kopfzeile | Wann | Bedeutung |
|---|---|---|
| `Content-Type` | immer | `application/json`; mit `Accept: application/problem+json` bei Fehlern `application/problem+json` |
| `X-Trace-Id` | immer | Spur-Kennung dieses Aufrufs, `trc_…`; identisch mit `traceId` im Fehlerrumpf |
| `X-Correlation-Id` | wenn der Aufruf eine Korrelations-Kennung führt | Kennung eines zusammenhängenden Vorgangs, `cor_…` |
| `ETag` | auf den Lese- und Änderungsrouten versionierter Ressourcen (Szenen, Playlisten, Programme, Rollen, Displays) | die `version` der Ressource als Kennzeichen, etwa `"7"`; beim Ändern als `If-Match` zurückschicken (siehe [ETag und If-Match](/de/api/etag-and-if-match)) |
| `Idempotent-Replay` | bei einer Wiederholung mit demselben `Idempotency-Key` | `true`: Die gespeicherte Antwort wurde geliefert, die Aktion lief nicht erneut |
| `X-RateLimit-Limit` | nur auf gedrosselten Routen | erlaubte Anfragen im Fenster |
| `X-RateLimit-Remaining` | nur auf gedrosselten Routen | davon noch offen |
| `X-RateLimit-Reset` | nur auf gedrosselten Routen | Beginn des nächsten Fensters in Unix-Sekunden |
| `Retry-After` | bei `429` und bei `502` mit Wartezeit | Sekunden bis zum nächsten erlaubten Versuch |
| `Server-Timing` | wenn die Plattform Zeitmessungen mitgibt | Dauer der Bearbeitung auf dem Server |

## Listen

Geblätterte Listen haben immer dieselbe Form:

| Feld | Bedeutung |
|---|---|
| `items` | die Datensätze dieser Seite |
| `nextCursor` | die Marke für die nächste Seite; fehlt auf der letzten Seite |
| `total` | die Gesamtzahl, wo die Route sie kennt — sonst fehlt das Feld |

Sie blättern mit den Abfrageparametern `limit` (Seitengröße) und `cursor` (Wert von `nextCursor`). Bei geblätterten Listen liegt `limit` zwischen 1 und 200 mit Vorgabe 50; die gefilterten Listen der Verwaltung (Geräte, Konten, Rollen, Schlüssel) deckeln bei 100 mit Vorgabe 25. Kleine, nicht blätterbare Bestände antworten mit einer einfachen Liste — die Form steht am Endpunkt in der Referenz.

## Kennungen

Jede Kennung besteht aus einem Präfix und 26 Zeichen im Crockford-Base32-Alphabet (Ziffern und Großbuchstaben ohne I, L, O und U), zum Beispiel `scn_01KJPX8NH0SZENE00000000001`. Das Präfix sagt, was die Kennung bezeichnet:

| Präfix | Bezeichnet |
|---|---|
| `tnt_` | Organisation |
| `usr_` | Benutzerkonto |
| `dev_` | Gerät |
| `ply_` | Display (in der API `playerId`) |
| `scn_` | Szene |
| `pll_` | Playlist |
| `sch_` | Programm (in der API `scheduleId`) |
| `ast_` | Medium |
| `fld_` | Ordner der Medien |
| `rol_` | Rolle |
| `whk_` | Webhook-Endpunkt |
| `whd_` | Webhook-Zustellung |
| `akm_` | API-Schlüssel (der Eintrag in Listen) |
| `adv_` | Werbepartner |
| `acp_` | Werbekampagne |
| `bkl_` | Buchung einer Werbekampagne |
| `crv_` | Motiv einer Buchung |
| `ppr_` | Planfassung eines Displays |
| `pss_` | Bildschirmaufnahme eines Displays |
| `pbt_` | Stapel von Ausspielungen, den ein Gerät gemeldet hat |
| `pcl_` | Abschluss einer Buchung über einen Zeitraum |
| `prf_` | Nachweis über einen Abschluss |
| `pfi_` | Datei eines Nachweises (PDF, Protokoll, Manifest, Bildschirmaufnahme) |
| `pdy_` | Zustellung eines Nachweises an einen Ansprechpartner des Werbepartners |
| `shl_` | Verweis, mit dem ein Werbepartner seine Nachweise ohne Konto öffnet |
| `rvs_` | Erlösaufstellung eines Standorts für einen Monat |
| `trc_` | Spur-Kennung eines Aufrufs |
| `cor_` | Korrelations-Kennung eines Vorgangs |

Der Schlüssel selbst beginnt mit `ak_` und ist ein Geheimwert: Er erscheint nur einmal bei der Ausstellung. In Listen steht seine Kennung `akm_…` und der Präfix `ak_` plus neun Zeichen zum Wiedererkennen.

## Fehlerrumpf

| Feld | Wann | Bedeutung |
|---|---|---|
| `code` | immer | stabiler Code in der Form `Bereich.Ursache`, etwa `Auth.Required` oder `Conflict.OptimisticLock` — darauf schalten Sie |
| `message` | immer | Kurztext für Menschen; nicht auswerten |
| `traceId` | immer, nie leer | Spur-Kennung `trc_…` für Rückfragen |
| `details` | wenn der Fehler Zusatzangaben trägt | etwa `issues` bei `Validation.Failed`, `expected`/`actual` bei `Conflict.OptimisticLock`; fehlt sonst ganz |
| `correlationId` | wenn der Aufruf eine Korrelations-Kennung führt | `cor_…` |
| `retryAfterSeconds`, `externalService` | nur bei Integrationsfehlern (`502`) | Wartezeit (auch als `Retry-After`) und der betroffene nachgelagerte Dienst |
| `stack` | nie im Produktivbetrieb | nur in Entwicklungsumgebungen bei internen Fehlern |

```json
{
  "code": "Scene.NotFound",
  "message": "Resource not found",
  "traceId": "trc_01KXWFT3H0SPR0000000000001"
}
```

Der HTTP-Status folgt dem Bereich des Codes: `Validation.*` → 422, `Auth.*` → 401, `Permission.*` → 403, `*.NotFound` → 404, `Conflict.*` → 409, `RateLimit.*` → 429, `Payload.*` → 413, `Integration.*` → 502. Einzelne Codes weichen ausdrücklich ab; die Seiten der Fehlercodes nennen für jeden Code den tatsächlich gesendeten Status.

## Fehler als Problem Details (RFC 9457)

Senden Sie `Accept: application/problem+json`, kommt derselbe Fehler als `ProblemDetails`-Dokument:

| Feld | Wann | Bedeutung |
|---|---|---|
| `type` | immer | Adressform des Codes, klein geschrieben mit Schrägstrichen |
| `title` | immer | Kurztitel des Codes |
| `status` | immer | der HTTP-Status |
| `detail` | immer | der Text von `message` |
| `code` | immer | derselbe Code wie im Standard-Rumpf |
| `instance` | nach Lage | der angefragte Pfad |
| `errorDetails` | nach Lage | dieselben Zusatzangaben wie `details` |
| `traceId`, `correlationId`, `retryAfterSeconds` | nach Lage | wie oben |

Ein `stack` gibt es in dieser Form nie.

## Zeitangaben

Alle Zeitpunkte sind Zeichenketten nach ISO 8601 mit Zeitzonen-Angabe, zum Beispiel `"createdAt": "2026-05-04T07:00:00.000Z"`. Ein fehlender Zeitpunkt steht als `null` (etwa `"expiresAt": null` für einen unbefristeten Schlüssel).

## Weiterführendes

- [Fehlerformat](/de/api/error-format)
- [Paginierung](/de/api/pagination)
- [ETag und If-Match](/de/api/etag-and-if-match)