Zum Inhalt springen
Szenera DeveloperHandbuch
Erste Schritte › Der erste Aufruf › Was eine Antwort enthält
Kapitel

Was eine Antwort enthält

Status, Kopfzeilen, Listenform, Kennungen mit Präfix und der Fehlerrumpf — alles, was in einer Antwort der API steckt, in Tabellen.

5 Minuten LesezeitErste SchritteStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

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

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.

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)
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 
{
  "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