# 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.

> **Typ:** fehlerhilfe
> **Für wen:** Entwicklerinnen und Entwickler, deren erster Aufruf nicht mit `200` antwortet
> **Voraussetzung:** die vollständige Fehlerantwort (Status, Kopfzeilen, Rumpf), etwa aus `curl -sSi`

## 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](/de/getting-started/first-call).

### 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](/de/getting-started/first-call).

### 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](/de/getting-started/create-api-key).

### 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](/de/api/authentication).

### 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](/de/getting-started/create-api-key).

### 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](/de/api/reference-areas).

### 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](/de/getting-started/create-api-key).

### 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](/de/api/base-url-and-stability).

### 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](/de/getting-started/response-contents#kennungen).

### 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](/de/api/error-format).

### 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](/de/api/rate-limits).

### 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](/de/getting-started/first-call).

## 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](/de/getting-started/create-api-key)
- [Der erste Aufruf mit curl](/de/getting-started/first-call)
- [Fehlercodes: Allgemein](/de/api/error-codes-general)