Zum Inhalt springen
Szenera DeveloperHandbuch
API › Fehlercodes › Fehlercodes: auf jeder Route möglich
Kapitel

Fehlercodes: auf jeder Route möglich

Die plattformweiten Codes für Anmeldung, Rechte, Validierung, Konflikte, Sperren, Nutzlast, HTTP, Ereignisse, Zwischenspeicher, Jobs und Ressourcen.

8 Minuten LesezeitAPIStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

Für wen
Wer eine Fehlerantwort einordnen muss, die nicht zu einer bestimmten Ressource gehört.
Voraussetzung
das Fehlerformat kennen — siehe Das Fehlerformat

Diese Codes entstehen in der Plattform-Schicht, nicht in einem Fachbereich — sie können auf jeder Route unter /v1 auftreten. Ihre Bereiche sind Anmeldung, Rechte, Eingabeprüfung, Konflikte, Drosselung, Nutzlast, HTTP sowie die Betreiberrouten für Ereignisse, Zwischenspeicher, Prüfprotokoll und Hintergrundaufträge.

So lesen Sie die Tabellen

Die Tabellen lesen Sie so: Code ist der Wert im Feld code des Fehlerrumpfs — darauf schaltet Ihre Logik, nie auf message. Bedeutung und Typischer Auslöser ordnen den Fall ein. HTTP ist der tatsächlich gesendete Status. Erwartete Reaktion ist die Antwort Ihres Clients in einem festen Wortschatz, der auf allen sieben Fehlercode-Seiten gleich ist: „Ausweis prüfen“ (401), „Recht oder Paket prüfen“ (402, 403), „Eingabe korrigieren“ (400, 413, 415, 422), „neu laden, erneut senden“ (Versionskonflikte), „nicht wiederholen, Vorgang prüfen“ (404, 409, 410, 426), „warten (Retry-After)“ (429) und „später erneut, bei Wiederholung Trace-Id melden“ (5xx).

Die Codes

Anmeldung (Auth)

Der Ausweis fehlt, ist ungültig oder abgelaufen. Fast alle Codes antworten 401, nur die unzulässige Sitzungsübernahme ist ein 403 und eine Fernwartung mit einer Protokoll-Fassung, die die Schnittstelle nicht bedient, ein 426. Für Integrationen sind Auth.ApiKeyRevoked, Auth.ApiKeyExpired und Auth.ApiKeyUnknown die drei, die Sie am ehesten sehen.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Auth.Required Authentifizierung erforderlich Anfrage ohne gültiges Token 401 Ausweis prüfen
Auth.TokenExpired Zugriffstoken abgelaufen Lebensdauer von 15 Minuten überschritten 401 Ausweis prüfen
Auth.TokenInvalid Token ungültig Manipuliertes oder unlesbares Token 401 Ausweis prüfen
Auth.TokenSignatureInvalid Token-Signatur ungültig Falscher Signierschlüssel 401 Ausweis prüfen
Auth.TokenKidUnknown Kennung des Signaturschlüssels unbekannt Token mit einer gewechselten Schlüsselkennung 401 Ausweis prüfen
Auth.TokenMalformed Token strukturell fehlerhaft Kein gültiges Zugriffstoken 401 Ausweis prüfen
Auth.SessionRevoked Sitzung widerrufen Abmeldung oder Beenden der Sitzung 401 Ausweis prüfen
Auth.MfaRequired Zweiter Faktor erforderlich Anmeldung ohne zweiten Faktor 401 Ausweis prüfen
Auth.MfaPending Schritt des zweiten Faktors ausstehend Zwischenschritt vor der Bestätigung des zweiten Faktors 401 Ausweis prüfen
Auth.MfaCodeInvalid Code des zweiten Faktors falsch Falscher Einmal- oder Wiederherstellungscode 401 Ausweis prüfen
Auth.ImpersonationNotPermitted Sitzungsübernahme nicht erlaubt Unzulässiger Versuch, eine fremde Sitzung zu übernehmen 403 Recht oder Paket prüfen
Auth.ApiKeyRevoked API-Schlüssel widerrufen Nutzung eines widerrufenen Schlüssels 401 Ausweis prüfen
Auth.ApiKeyExpired API-Schlüssel abgelaufen Ablaufdatum überschritten 401 Ausweis prüfen
Auth.ApiKeyUnknown API-Schlüssel unbekannt Der Schlüssel existiert nicht 401 Ausweis prüfen
Auth.OAuthTokenRevoked Delegierter Zugang zurückgenommen Die Person hat die Einwilligung entzogen, der Betrieb die Anwendung gesperrt, oder ein bereits getauschtes Erneuerungs-Token kam ein zweites Mal — dann erlischt die ganze Token-Familie 401 Ausweis prüfen
Auth.OAuthClientBlocked Verbundene Anwendung gesperrt Der Betrieb hat diese Anwendung gesperrt. Von ihr wird kein Token mehr angenommen, auch kein frisch erneuertes 401 Ausweis prüfen
Auth.CertMalformed Gerätezertifikat fehlerhaft Ungültiges Gerätezertifikat 401 Ausweis prüfen
Auth.CertNotTrusted Zertifikat nicht vertrauenswürdig Nicht von der Zertifikatsstelle der Plattform ausgestellt 401 Ausweis prüfen
Auth.CertExpired Zertifikat abgelaufen Geräte-Zertifikat abgelaufen 401 Ausweis prüfen
Auth.CertRevoked Zertifikat gesperrt Auf der Sperrliste 401 Ausweis prüfen
Auth.DeviceBlocked Gerät gesperrt Ein gesperrtes Gerät weist sich mit seinem Zertifikat aus. Abgewiesen, bis der Betreiber die Sperre aufhebt 401 Ausweis prüfen
Auth.DeviceDecommissioned Gerät stillgelegt (Altbestand) Wird nicht mehr ausgegeben. Der Geräte-Agent liest den Code weiter als Auftrag zum Werkszustand 401 Ausweis prüfen
Protocol.VersionNotServed Protokoll-Fassung wird nicht bedient Eine Fernwartung nennt im Kopf User-Agent eine Fassung ihres Protokolls, die die Schnittstelle nicht bedient. details.served nennt den bedienten Bereich. Ein zweiter Versuch ändert daran nichts, abhelfen kann nur ein passendes Paket der Fernwartung 426 nicht wiederholen, Vorgang prüfen
Auth.RendererTokenExpired Abspieler-Token abgelaufen Lebensdauer von 4 Stunden überschritten 401 Ausweis prüfen
Auth.RendererTokenRevoked Abspieler-Token widerrufen Abspieler-Sitzung widerrufen 401 Ausweis prüfen
Auth.InvitationConsumed Einladungs-Token verbraucht Bereits eingelöste Einladung 401 Ausweis prüfen
Auth.InvitationExpired Einladungs-Token abgelaufen Abgelaufene Einladung 401 Ausweis prüfen
Auth.UserSuspended Konto gesperrt Anmeldung oder Anfrage eines gesperrten Kontos 401 Ausweis prüfen
Auth.TenantSuspended Organisation gesperrt Zugriff auf eine gesperrte Organisation 401 Ausweis prüfen

Rechte (Permission)

Der Ausweis ist gültig, aber das Recht fehlt. Alle Codes antworten 403. Permission.OperatorOnly bekommen Sie, wenn ein Schlüssel oder eine Sitzung einer Organisation eine Route unter /v1/platform/… aufruft — bewusst kein 401, damit ein Prozess nicht in eine Anmeldeschleife läuft.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Permission.Denied Berechtigung fehlt Das nötige Recht fehlt 403 Recht oder Paket prüfen
Permission.OperatorOnly Route nur für Betreiber-Konten Sitzung oder Schlüssel einer Organisation auf einer /v1/platform/…-Route. Eigener Code statt Auth.Required, weil ein Prozess auf 401 die Anmeldung wiederholt und sich im Kreis dreht — hier hilft kein neuer Ausweis, sondern nur eine andere Route 403 Recht oder Paket prüfen
Permission.UnknownKey Unbekannter Rechte-Schlüssel Nicht im Katalog 403 Recht oder Paket prüfen
Permission.OwnershipDenied Objekt-Zugriff verweigert Keine Erteilung für die Ressource 403 Recht oder Paket prüfen
Permission.ResourceIdMissing Ressourcen-Kennung fehlt Objektgebundene Prüfung ohne Kennung 403 Recht oder Paket prüfen

Eingabeprüfung (Validation)

Rumpf, Parameter oder Kopfzeilen verletzen das Schema oder eine Regel. Regelfall 422, nur die fehlende Idempotenz-Kopfzeile auf einer Route, die sie erzwingt, antwortet 409.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Validation.Failed Eingabe ungültig Rumpf oder Parameter verletzen das Schema 422 Eingabe korrigieren
Validation.IdempotencyKeyRequired Idempotency-Key erforderlich Mutation ohne Idempotency-Key 409 nicht wiederholen, Vorgang prüfen
Validation.IdempotencyKeyReused Idempotency-Key mit anderem Rumpf Derselbe Schlüssel für einen zweiten, inhaltlich anderen Vorgang 422 Eingabe korrigieren
Validation.UrlProtocolBlocked URL-Protokoll blockiert Nicht erlaubtes Schema (z. B. file:) 422 Eingabe korrigieren
Validation.UrlProtocolNotAllowed URL-Protokoll nicht zulässig Protokoll außerhalb der Freigabeliste 422 Eingabe korrigieren
Validation.FileTypeUnsupported Dateityp nicht unterstützt Upload eines unzulässigen Formats 422 Eingabe korrigieren
Validation.PathTraversalBlocked Pfad-Traversal blockiert ../ in einem Pfad-Parameter 422 Eingabe korrigieren

Konflikte (Conflict)

Der Zustand der Ressource lässt die Aktion nicht zu, oder jemand anderes hat gleichzeitig geschrieben. Alle Codes antworten 409. Conflict.OptimisticLock ist der Fall aus Gleichzeitige Änderungen.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Conflict.OptimisticLock Versionskonflikt If-Match/expectedVersion veraltet 409 neu laden, erneut senden
Conflict.DuplicateKey Eindeutigkeit verletzt Doppelter Wert in einem eindeutigen Feld 409 nicht wiederholen, Vorgang prüfen
Conflict.ReferenceConstraint Verweis-Bedingung verletzt Verweis auf einen nicht vorhandenen Datensatz 409 nicht wiederholen, Vorgang prüfen
Conflict.ResourceLocked Ressource gesperrt Konkurrierender Zugriff 409 neu laden, erneut senden

Drosselung (RateLimit)

Zu viele Anfragen im Fenster. Alle Codes antworten 429 mit Retry-After. Welche Routen gedrosselt sind, steht unter Drosselung.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
RateLimit.Exceeded Rate-Limit überschritten Zu viele Anfragen 429 warten (Retry-After)
RateLimit.GlobalCircuitBreaker Globaler Circuit-Breaker offen Plattformweite Überlast-Sicherung 429 warten (Retry-After)

Nutzlast (Payload)

Der Rumpf ist zu groß oder in einer Kodierung, die der Server nicht verarbeitet. Alle Codes antworten 413.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Payload.TooLarge Body zu groß Limit überschritten 413 Eingabe korrigieren
Payload.UnsupportedEncoding Kodierung nicht unterstützt Nicht verarbeitbare Content-Encoding 413 Eingabe korrigieren

Herkunft und HTTP (Cors, Http)

Ablehnung einer Browser-Herkunft und die allgemeinen HTTP-Fehler: falsche Methode, falscher Medientyp, unlesbare Anfrage.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Cors.OriginRejected Origin nicht erlaubt Anfrage von unzulässiger Herkunft 403 Recht oder Paket prüfen
Http.BadRequest Fehlerhafte Anfrage Anfrage, die der Server nicht lesen kann 400 Eingabe korrigieren
Http.MethodNotAllowed Methode nicht erlaubt Falsches HTTP-Verb 405 Eingabe korrigieren
Http.UnsupportedMediaType Medientyp nicht unterstützt Falscher Content-Type 415 Eingabe korrigieren

Ereignisse (Events)

Routen des Plattformbetriebs zur erneuten Zustellung von Ereignissen. Mit einem Schlüssel einer Organisation erreichen Sie sie nicht.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Events.EventNotFound Ereignis nicht gefunden Erneute Zustellung eines unbekannten Ereignisses 404 nicht wiederholen, Vorgang prüfen
Events.EventNotReplayable Ereignis nicht wiederholbar Erneute Zustellung eines nicht wiederholbaren Ereignisses 409 nicht wiederholen, Vorgang prüfen
Events.BulkReplayLimitExceeded Grenze der Sammel-Wiederholung überschritten Zu viele Ereignisse auf einmal 422 Eingabe korrigieren

Zwischenspeicher (Cache)

Routen des Plattformbetriebs zum Verwerfen von Zwischenspeicher-Einträgen.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Cache.PatternMatchingInvalid Ungültiges Zwischenspeicher-Muster Fehlerhaftes Muster zum Verwerfen 400 Eingabe korrigieren
Cache.OpsInvalidateReasonTooShort Begründung zu kurz Verwerfen ohne ausreichende Begründung 400 Eingabe korrigieren

Prüfprotokoll der Plattform (Audit)

Routen des Plattformbetriebs für den Wechsel des Pseudonymisierungsschlüssels und die Auflösung von Pseudonymen.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Audit.RotationCooldownActive Sperrfrist des Schlüsselwechsels aktiv Wechsel des Pseudonymisierungsschlüssels zu früh erneut 409 nicht wiederholen, Vorgang prüfen
Audit.LookupRateLimitExceeded Abfrage-Häufigkeit überschritten Zu viele Pseudonym-Abfragen 429 warten (Retry-After)

Hintergrundaufträge (Jobs)

Routen des Plattformbetriebs für Warteschlangen und endgültig fehlgeschlagene Aufträge.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Jobs.JobNotFound Auftrag nicht gefunden Aktion auf einen unbekannten Auftrag 404 nicht wiederholen, Vorgang prüfen
Jobs.JobNotKillable Auftrag nicht abbrechbar Erzwungener Abbruch nicht möglich 409 nicht wiederholen, Vorgang prüfen
Jobs.DeadLetterNotFound Eintrag der endgültig fehlgeschlagenen Aufträge fehlt Erneutes Einstellen eines unbekannten Eintrags 404 nicht wiederholen, Vorgang prüfen
Jobs.ReplayAlreadyDone Erneutes Einstellen bereits erfolgt Doppeltes erneutes Einstellen 409 nicht wiederholen, Vorgang prüfen
Jobs.BulkReplayLimitExceeded Grenze der Sammel-Wiederholung überschritten Zu viele Aufträge auf einmal 422 Eingabe korrigieren

Ressourcen (Resource)

Der allgemeine Rückfall, wenn keine Route zum Pfad passt.

Code Bedeutung Typischer Auslöser HTTP Erwartete Reaktion
Resource.NotFound Ressource nicht gefunden Generischer 404-Fallback 404 nicht wiederholen, Vorgang prüfen

Zählsatz

Diese Seite führt 66 Codes. Zusammen mit den übrigen sechs Fehlercode-Seiten ergeben sich 493 fachliche Codes (4xx) und 119 Serverfehler (5xx), also 612 Codes — der vollständige Katalog der Plattform.

Gezählt wird dabei nach der Art des Fehlers und nicht nach dem gesendeten Status: Als fachlich zählen die 493 Codes, auf die Ihr Client gezielt reagieren kann — neun von ihnen antworten trotzdem mit einem 5xx, weil ein nachgelagerter Dienst ausfällt, das Haus für einen Augenblick nicht rechenbereit ist oder ihm ein Zugang fehlt —, als Serverfehler die 119, bei denen nur Wiederholen oder Melden bleibt. Nach dem Status allein gezählt wären es 484 und 128.

Weiterführendes