Wenn der erste Aufruf scheitert

Die Symptome stehen in der Reihenfolge, in der sie beim ersten Aufruf am häufigsten auftreten. Lesen Sie zuerst den Status, dann das Feld code im Fehlerrumpf — und heben Sie die traceId auf, falls Sie nachfragen müssen.

Symptome nach Häufigkeit#

401 mit Auth.Required#

Bedeutung: Die Kopfzeile Authorization fehlt, das Wort Bearer davor fehlt, oder der Wert hat kein bekanntes Präfix (Tippfehler im Präfix). Die Plattform behandelt einen unbrauchbaren Ausweis nie als anonym — auch ein Wert mit unbekanntem Präfix landet hier und nicht bei einer 404.

Lösung: Prüfen Sie, dass die Kopfzeile genau Authorization: Bearer ak_… lautet und die Umgebungsvariable gefüllt ist (echo "$SZENERA_API_KEY" | cut -c1-3 muss ak_ zeigen). Kommandozeile: Exit-Code 3. Siehe Der erste Aufruf mit curl.

401 mit Auth.TokenMalformed#

Bedeutung: Das Präfix ak_ stimmt, aber der Rest entspricht nicht dem Muster eines Schlüssels: genau 26 Zeichen aus Ziffern und Großbuchstaben ohne I, L, O und U. Typisch ist ein beim Kopieren abgeschnittener Schlüssel oder ein Wert mit fremden Zeichen — Leerzeichen, Anführungszeichen, Kleinbuchstaben.

Lösung: Übernehmen Sie den Wert vollständig aus Ihrem Geheimnis-Speicher und prüfen Sie die Länge (echo -n "$SZENERA_API_KEY" | wc -c muss 29 ergeben). Kommandozeile: Exit-Code 3. Siehe Der erste Aufruf mit curl.

401 mit Auth.ApiKeyUnknown, Auth.ApiKeyRevoked oder Auth.ApiKeyExpired#

Bedeutung: Präfix und Muster stimmen, aber der Schlüssel existiert nicht (Tippfehler im Wert, der die 26 Zeichen noch erfüllt), wurde widerrufen oder hat sein Datum unter Gültig bis überschritten.

Lösung: Erzeugen Sie einen neuen Schlüssel und tauschen Sie den Wert in Ihrem Geheimnis-Speicher. Ein widerrufener Schlüssel kommt nicht zurück. Siehe Einen API-Schlüssel erzeugen.

401 mit Auth.TokenExpired#

Bedeutung: Sie senden ein Sitzungstoken (eyJ…) aus der Anmeldung; es ist nach 15 Minuten abgelaufen.

Lösung: Für Maschinen einen Schlüssel ak_… verwenden. Wer die Anmeldewege braucht, findet die Auffrischung unter Anmeldung.

403 mit Permission.Denied#

Bedeutung: Der Ausweis gilt, trägt aber das Recht der Operation nicht. Jede Operation nennt ihr Recht in der Referenz (etwa identity.device.list); ein Schlüssel hat nur die Rechte, die beim Anlegen gewählt wurden. Einige Rechte tragen Schlüssel nie — etwa identity.device.list (Geräte), fleet.playback-history.read (die Tages-Rückschau eines Displays) und identity.api-key.create; diese Routen erreichen Sie nur mit einem Sitzungstoken.

Lösung: Prüfen Sie im Portal unter Einstellungen › Organisation › API-Schlüssel die Spalten Name / Rechte und Klasse des Schlüssels; fehlt das Recht, erzeugen Sie einen Schlüssel mit passender Klasse oder ergänzen es über Einzelne Rechte anpassen. Kommandozeile: Exit-Code 4. Siehe Einen API-Schlüssel erzeugen.

403 mit Permission.OperatorOnly#

Bedeutung: Die Route unter /v1/platform/… steht nur dem Plattformbetrieb offen. Ein Schlüssel einer Organisation kommt dort nie hinein; hier hilft kein neuer Ausweis, sondern eine andere Route.

Lösung: Die Route der Organisation verwenden (etwa GET /v1/playlists statt einer Route unter /v1/platform). Siehe Bereiche der Referenz.

402 mit Billing.AddonRequired#

Bedeutung: Beim Anlegen oder Rotieren eines Schlüssels: Das Paket der Organisation enthält den API-Zugang nicht. Bestehende Schlüssel arbeiten weiter, nur Neue verlangen die Freischaltung.

Lösung: Paket ab Premium („API und Webhooks“) oder die vertragliche Freischaltung des API-Zugangs. Siehe Einen API-Schlüssel erzeugen.

404 mit Resource.NotFound#

Bedeutung: Der Pfad trifft keine Route. Beim ersten Aufruf fast immer: /v1 fehlt (/me statt /v1/me), ein Tippfehler im Pfad, oder die Basis-Adresse zeigt auf das Portal statt auf die API.

Lösung: Adresse und Pfad prüfen; jede Route beginnt mit /v1. Kommandozeile: Exit-Code 5. Siehe Basis-URL, /v1 und Stabilität.

404 mit <Ressource>.NotFound (etwa Scene.NotFound, Device.NotFound)#

Bedeutung: Die Route stimmt, aber die Kennung gehört nicht zu Ihrer Organisation oder existiert nicht mehr. Eine fremde Kennung ist von einer erfundenen nicht zu unterscheiden — beides ist dieselbe 404.

Lösung: Kennung aus einer Liste Ihrer Organisation übernehmen (GET /v1/scenes, GET /v1/playlists, …) und das Präfix mit der Ressource abgleichen (scn_ für Szenen, pll_ für Playlisten). Siehe Was eine Antwort enthält.

422 mit Validation.Failed#

Bedeutung: Ein Parameter oder ein Feld im Rumpf verletzt den Vertrag — etwa limit=500, wo höchstens 200 gilt, ein fehlendes Pflichtfeld oder ein falscher Typ.

Lösung: Lesen Sie details.issues: Jeder Eintrag nennt den Feldpfad und den Verstoß. Kommandozeile: Exit-Code 7; die Kommandozeile prüft einen selbst geschriebenen Rumpf schon vor dem Senden und meldet den Feldpfad mit Exit-Code 1. Siehe Fehlerformat.

429 mit RateLimit.Exceeded#

Bedeutung: Zu viele Anfragen in einem Fenster. Gedrosselt sind vor allem die missbrauchsnahen Routen — Anmeldung, Registrierung, Passwort-Zurücksetzen; einzelne weitere Routen nennen es in der Referenz. Ihr erster Aufruf mit Schlüssel trifft sie nicht; wer die Anmeldung in einer Schleife wiederholt, schon.

Lösung: Die Kopfzeile Retry-After nennt die Sekunden bis zum nächsten erlaubten Versuch; X-RateLimit-Reset den Beginn des nächsten Fensters. Warten, dann wiederholen — und für Maschinen einen Schlüssel statt der Anmeldung verwenden. Kommandozeile: Exit-Code 8. Siehe Drosselung und Rate-Limit-Kopfzeilen.

Keine HTTP-Antwort: Verbindung verweigert, Zeitüberschreitung, TLS-Fehler#

Bedeutung: Der Aufruf hat die Plattform nicht erreicht. Die Basis-Adresse ist falsch, der Port fehlt oder ist falsch, das Zertifikat passt nicht zum Namen, oder ein Proxy blockiert.

Lösung: Erst die Adresse ohne Ausweis prüfen — szenera health fragt die öffentliche Bereitschaftsroute Ihrer Umgebung ab und scheitert nicht an der Anmeldung; so sieht ein falscher Port nicht aus wie ein falscher Schlüssel. Kommandozeile: Exit-Code 10. Danach Schritt 1 unter Der erste Aufruf mit curl.

Die Trace-Kennung aufheben#

Jede Fehlerantwort trägt traceId im Rumpf und X-Trace-Id in der Kopfzeile — derselbe Wert trc_…. Er ist die Spur genau dieses Aufrufs auf der Plattform. Wenn Sie nachfragen, nennen Sie ihn; ohne ihn lässt sich ein einzelner Aufruf nicht wiederfinden.

Weiterführendes#

• Einen API-Schlüssel erzeugen
• Der erste Aufruf mit curl
• Fehlercodes: Allgemein