Dokumentation
Fehlerbehebung

ALKM-Antworten und fehlgeschlagene Aufrufe

Fehlercodes, leere Ergebnisse, Timeouts und unterschiedliche Rücknahmewege einordnen.

Auf dieser Seite

Prüfen Sie bei ALKM-Fehlern den HTTP-Status, den JSON-Body und den tatsächlichen Zustand nach dem Aufruf. Insbesondere bei Schreibzugriffen bedeutet eine fehlende Antwort nicht, dass nichts gespeichert wurde.

HTTP 200, aber der Aufruf wurde abgelehnt

Die Playout-Endpunkte validate und enroll melden fachliche Ablehnungen auch mit HTTP 200:

{"code":-2,"message":"licence expired"}

Bei Antworten mit code ist nur 1 Erfolg. Auch 0 ist ein Fehler. Direkte Listen wie die Ausgabe von signatures haben dieses Feld dagegen nicht.

Fehlercodes einordnen

Code Bedeutung Was prüfen?
0 Interner oder nicht genauer zugeordneter Fehler Zustand vor Wiederholung prüfen, Support hinzuziehen
-1 Ungültige Lizenz Code, Sperre, Eingabekombination und verwendeten Endpunkt
-2 Abgelaufen expires, Einlösefenster und Aktivierungsweg
-3 Nutzungslimit erreicht Nutzerplätze und bestehende Aktivierungen
-4 Ungültige Daten JSON-Syntax, Feldnamen und Datentypen
-101 Zugang nicht zulässig Schlüssel, Schlüsseltyp, Reseller-Einschränkung
-102 Fehlender Anbieter-Kontext Admin-Aufruf und vereinbarten x-vendor-Header
-103 Noch nicht gültig validfrom
-104 Nicht gefunden Suchdaten und Sichtbarkeitsrechte
-105 E-Mail bereits verwendet Vorhandenes Konto statt Neuanlage prüfen
-106 Nicht erlaubt Anbieter-/Produktberechtigung
-107 Benutzer nicht gefunden Tatsächliche Konto-ID

Nicht jeder Endpunkt gibt jeden Code zurück. Die HTTP-Statuswerte sind nicht global an einen Fehlercode gebunden: Eine bereits verwendete E-Mail ergibt bei Kontoanlage beispielsweise HTTP 404; fachliche Aktivierungsfehler können mit HTTP 500 auftreten. Der fehlende Anbieter-Kontext wird in der Management-Middleware derzeit mit HTTP 403 und code: -101 gemeldet, obwohl auch der allgemeine Fehlercode -102 definiert ist.

Bei /licence/key/info/{key} ergibt ein unbekannter Code HTTP 200 mit code: -1, ein unpassender Anbieter-Kontext HTTP 403 mit code: -106. Beim Kontoentzug /user/manage/licence/revoke werden Fehler der Speicherlogik dagegen einheitlich als HTTP 500 mit code: 0 und message: "unexpected error" ausgegeben. Dazu gehören auch ein unbekannter Code oder fehlende Produktberechtigungen. Nicht automatisch wiederholen, sondern zunächst den Zustand und die Berechtigungen prüfen.

Keine oder zu wenige Codes erhalten

  1. amount muss eine positive Ganzzahl sein. Ohne Angabe wird nicht automatisch ein Code bestellt.
  2. Prüfen Sie, ob die Produktnummer für den Reseller freigegeben ist. Nicht freigegebene Produkte können ohne Fehler aus dem Ergebnis entfallen.
  3. Bei vorgenerierten Codes muss genügend Vorrat vorhanden sein.
  4. Für XLSX einzelne Request-Objekte verwenden: Bei Arrays verweist xlsx_download nur auf die letzte Position. Ab 100 Codes einer Position wird die bisher angesammelte JSON-Lizenzliste geleert; spätere Positionen können sie wieder befüllen. Der Warenkorb-Code steht nicht in den Dateien. Antwort und Download können zusammen unvollständig sein. Für Warenkörbe und den ersten Integrationstest die einfache /keys/create-Route verwenden.
  5. Bei Warenkörben müssen Produktcodes und der zusätzliche cart-Code vorhanden sein. Vergleichen Sie Produktnummern und Mengen mit Ihrer Bestellung.

XLSX-Dateien zeitnah herunterladen. ALKM fordert Downloadlinks mit 5 Minuten Laufzeit für /xlsx und 14 Tagen für /sxlsx an; die Durchsetzung übernimmt der Downloaddienst. Die Links sind keine dauerhafte Dateiablage.

Kontoänderung meldet OK, aber Daten bleiben unverändert

Verwenden Sie user_id im Format $/csu/123/bk und die tatsächlich zurückgegebene ID. Die Änderung ist auf die passende Reseller-Anlagekennung beschränkt. Der Endpunkt bestätigt auch Aufrufe, die keine Zeile ändern. Lesen Sie das Konto danach mit /user/manage/info erneut aus.

Eine aktive Lizenz lässt sich nicht mehr nutzen

/user/manage/licence/active listet aktive Codezuordnungen. Die Liste filtert nicht alle Datumsbedingungen heraus. Prüfen Sie die Laufzeiten und den Zugriff über den vorgesehenen Einlöse- beziehungsweise Nutzungsweg. Verwechseln Sie eine historische Aktivierung nicht mit einem aktuellen Nutzungsrecht.

Timeout nach Code-Erzeugung oder Aktivierung

Wiederholen Sie den Auftrag nicht sofort. Notieren Sie Zeitpunkt mit Zeitzone, Endpunkt und eigene Bestellreferenz. Prüfen Sie bereits zurückgegebene Codes beziehungsweise die aktive Kontoliste. Wenn Ihr Schlüssel keine Suchberechtigung hat, lassen Sie den Zustand vom Support prüfen.

Ein Warenkorb kann teilweise verarbeitet sein. internal_order_number und purchase_reference sind Zuordnungsfelder, keine Idempotenzschlüssel.

Rücknahme ist nicht gleich Löschen

Der Kontoentzug /user/manage/licence/revoke betrifft die Zuordnung zu einer Person. Die Management-Routen /keys/revoke/{key} und /keys/delete/{key} haben andere Auswirkungen und sind für Reseller gesperrt. Code-Löschen allein ist kein zugesicherter Entzug bereits angelegter Kontolizenzen. Nutzen Sie es nicht als Ersatz für einen abgestimmten Stornoprozess.

Für eine Supportanfrage genügen zunächst Endpunkt, Zeitpunkt, HTTP-Status, Fehlercode und Bestellreferenz. API-Schlüssel und Passwörter gehören nie hinein. Übermitteln Sie nutzerbezogene Daten oder einlösbare Codes nur über den vereinbarten geschützten Supportweg.

Zugang und Berechtigungen: Einstieg in die ALKM-API. Feldreferenz: ALKM-Felder und Antwortformate. Externe Codeprüfung: Freischaltcodes in externen Anwendungen prüfen und einlösen.