Troubleshooting

Fehlerbild → Ursache → Lösung. Für Grundlagen zu Fehlercodes siehe den API-Einstieg; häufige Verständnisfragen klärt die FAQ.

Anmeldung schlägt fehl oder Konto ist gesperrt

Ursache. Entweder falsche Zugangsdaten, oder nach 5 Fehlversuchen ist das Konto 15 Minuten gesperrt (Schutz vor Brute-Force). Ein deaktiviertes Konto meldet sich ebenfalls nicht an.

Lösung. 15 Minuten warten und erneut versuchen, oder einen Administrator die Sperre aufheben bzw. das Kennwort zurücksetzen lassen (Passwort zurücksetzen). Über die API äußert sich die Sperre bzw. Deaktivierung als 403, falsche Zugangsdaten als 401.

Der 2FA-Code wird nicht akzeptiert

Ursache. Meist eine Uhrzeit-Abweichung des Geräts (TOTP-Codes sind zeitbasiert), ein bereits abgelaufener Code oder das falsche Authenticator-Konto. Über die API kommt 428 (2FA aktiv, aber totp_code fehlt) bzw. 401 (Code falsch).

Lösung. Automatische Zeitsynchronisation am Gerät aktivieren, einen frischen Code abwarten und zügig eingeben. Kein Zugriff mehr auf den Authenticator? Melde dich über ein zweites hinterlegtes Gerät an. Hast du gar kein Gerät mehr, setzt ein Administrator deine 2FA zurück. Backup-Codes gibt es nicht. Siehe 2FA einrichten.

Modul nicht sichtbar oder ausgegraut

Ursache. Drei mögliche Gründe, in dieser Reihenfolge zu prüfen:

Tarif. Das Modul gehört zu einem höheren Tarif (viele Module ab Professional, Provisionierung/Webhooks ab Elite).
Instanzweit deaktiviert. Ein Super-Admin hat das Modul global abgeschaltet.
Rolle. Deine Rolle hat keine Berechtigung für den Bereich.

Lösung. Tarif und Limits prüfen (Limits verstehen); Modul ggf. aktivieren (Module aktivieren); Rolle abgleichen (Rollen & Berechtigungen). Ein gesperrtes Modul zeigt in der Oberfläche einen Upgrade-Hinweis.

401 bei API-Aufrufen

Ursache. Nicht authentifiziert: der Token fehlt, ist falsch geschrieben, abgelaufen oder widerrufen.

Lösung. Header exakt setzen: Authorization: Bearer inv_…. Token-Präfix und Gültigkeit prüfen; im Zweifel neu erstellen (Token erstellen). Der Token wird nur einmal bei der Erstellung im Klartext angezeigt. Ein verlorener Token lässt sich nicht auslesen, nur ersetzen.

403 bei API-Aufrufen

Ursache. Authentifiziert, aber nicht erlaubt. Drei Familien unterscheiden:

Limit erreicht: z. B. "Asset limit reached (2500) for the 'professional' plan…".
Modul nicht im Tarif: Feature-Gating (z. B. Webhooks ohne Elite).
Rolle/Scope zu gering: schreibender Zugriff mit read-Token oder ohne passende Rolle.

Lösung. Fehlt Kapazität, altes/gelöschtes aufräumen (Papierkorb zählt mit!) oder Tarif anheben; fehlt das Feature, Tarif/Modul prüfen (Limits verstehen); beim Scope einen Token mit write verwenden (API-Einstieg).

422 Validierungsfehler

Ursache. Die Nutzdaten sind unvollständig oder falsch typisiert: z. B. leerer name, unbekannter asset_type, falsches Datumsformat.

Lösung. Die Antwort nennt unter detail Feld und Grund: genau dieses Feld korrigieren. Erlaubte Werte stehen in der API-Referenz beim jeweiligen Endpunkt.

429: zu viele Anfragen

Ursache. Das Rate-Limit (Standard 60 Anfragen/Minute pro IP, v. a. auf Auth-Endpunkten) ist überschritten.

Lösung. Den Retry-After-Header auswerten und ein Backoff einbauen; parallele Schleifen entzerren. Für Massenoperationen die Paginierung (page_size bis 100) statt vieler Einzelaufrufe nutzen.

CSV-Import: es fehlen Zeilen

Ursache. Ungültige Zeilen werden still übersprungen (nur im Log vermerkt), ohne Fehlercode. Typische Auslöser: leerer name, unbekannter asset_type, oder eine leere Zelle in einer typisierten Spalte (Datum/Zahl/Enum). Letzteres kippt die ganze Zeile.

Lösung. Die Ergebnismeldung nennt die Zahl der übersprungenen Datensätze. Pflichtspalten asset_type (gültiger Wert) und name (nicht leer) sicherstellen, typisierte Spalten leer lassen oder korrekt füllen, dann die übersprungenen Zeilen erneut importieren. Voller Ablauf: CSV-Import. Achtung: erneuter Import bereits vorhandener Zeilen erzeugt Dubletten (keine Duplikat-Erkennung).

Webhook kommt nicht an

Ursache. Es wird produktiv nur asset.created ausgelöst. Für andere Aktionen kommt (noch) nichts. Zudem gibt es keinen automatischen Retry: Jedes Ereignis wird höchstens einmal zugestellt (Timeout 10 s); ein langsamer oder kurz nicht erreichbarer Empfänger verpasst es.

Lösung. Erwartetes Event prüfen (Events); Empfänger-Endpunkt schnell (< 10 s) mit 2xx antworten lassen; das Zustellprotokoll (letzte Zustellungen) kontrollieren und verpasste Daten per API nachziehen (Fehler & Retry). Kommt „etwas, aber Verifikation schlägt fehl”, die Signatur X-Webhook-Signature: sha256=… gegen den Roh-Body prüfen (Signatur verifizieren).

SSO-Button erscheint nicht

Ursache. Die E-Mail-Discovery greift nur für die exakte E-Mail-Adresse eines bereits existierenden Kontos (nicht pro Domain). Neue Benutzer sehen deshalb keinen „Anmelden mit …”-Button.

Lösung. Konto zuerst anlegen lassen; danach greift die Erkennung. Alternativ den direkten Start-Link des Anbieters nutzen. Einrichtung und Verhalten: E-Mail-Discovery und SSO einrichten.

Neue Lizenz wird nicht erkannt

Ursache. Die Produktlizenz wird nicht in der Oberfläche hochgeladen, sondern als Umgebungsvariable LICENSE_KEY hinterlegt und greift erst nach einem Neustart des Servers.

Lösung. LICENSE_KEY vollständig (einzeilig) in die .env eintragen, Notory neu starten, dann unter Verwaltung → Lizenz die Stufe prüfen und je Mandant die Lizenzstufe setzen. Anleitung: Lizenz einspielen.

QR-Code oder Bild lädt nicht

Ursache. Der QR-Endpunkt (/api/v1/assets/{id}/qr) liefert ein PNG nur mit gültiger Authentifizierung. Ein Aufruf ohne Bearer-Token bzw. Session bekommt 401.

Lösung. Beim programmatischen Abruf den Authorization-Header mitsenden; in der Oberfläche den Download „QR-Code herunterladen” in der Asset-Detailansicht nutzen. Scannen und QR-Nutzung: Asset-QR-Code scannen.