Widget-Fehlerbehebung

Fehler erscheinen im Widget als Alert und zusätzlich als Event orbinaut:error mit { code, phase, retryable }. Die Texte kommen aus dem Embed-Vertrag. Kopiere für Support-Anfragen den Code, nie den Widget-Key und keine Teilnehmerdaten.

Achtung

Ein ungültiger, rotierter oder deaktivierter Key sieht für die Host-Seite aus wie ein nicht mehr verfügbares Widget. Das ist Absicht.

Checkliste vor dem Debuggen

1. Script-URL ist YOUR_WEB_ORIGIN/widget/v1/orbinaut-widget.js.
2. api-url ist die API-Origin ohne Pfad.
3. widget-key beginnt mit orb_widget_v1_ und stammt aus dem einmaligen Dialog.
4. Das Widget ist im Dashboard Aktiv.
5. Die Host-Origin steht exakt in Erlaubte Domains, falls die Liste nicht leer ist.
6. CSP erlaubt script-src für die Web-Origin und connect-src für die API-Origin.

Sichtbare Meldungen

Code	Sichtbarer Text	Typische Ursache	Nächster Schritt	Erneut versuchen
CONFIGURATION_ERROR	Das Widget ist nicht vollständig konfiguriert.	Attribut fehlt, api-url ist kein Origin, Key ohne Präfix orb_widget_v1_.	Embed mit Dashboard-Code vergleichen.	nein
WIDGET_KEY_INVALID	Dieses Widget ist nicht mehr verfügbar.	Unbekannter, rotierter oder deaktivierter Key.	Key rotieren oder Widget aktivieren; neuen Embed einsetzen.	nein
ORIGIN_NOT_ALLOWED	Dieses Widget darf auf dieser Website nicht angezeigt werden.	Host-Origin fehlt in Erlaubte Domains oder weicht ab (www, Trailing-Slash, anderes Schema).	Exakte Origin eintragen, z. B. https://www.beispiel.de.	nein
NETWORK_ERROR	Das Widget konnte nicht geladen werden. Prüfe Netzwerk- und CSP-Einstellungen.	connect-src blockiert, falsche api-url, Offline.	CSP und API-Origin prüfen.	ja
RATE_LIMITED	Das Widget wurde zu häufig aufgerufen. Bitte versuche es später erneut.	Mehr als 120 API-Aufrufe / 60 s je Widget.	Warten und Reload; Einbindungen bündeln.	ja
RESOURCE_NOT_FOUND (Laden)	Die Widget-Inhalte sind nicht mehr verfügbar.	Scope oder Kurs nicht mehr öffentlich.	Filter und Kursstatus im Dashboard prüfen.	nein
RESOURCE_NOT_FOUND (Buchung)	Dieser Kurs kann nicht mehr gebucht werden.	Kurs zwischen Auswahl und Submit entfernt oder voll.	Kursliste neu laden.	nein
BOOKING_CONFLICT	Der Platz ist nicht mehr verfügbar oder diese E-Mail-Adresse ist bereits gebucht.	Kapazität oder Dublette.	Andere E-Mail oder anderen Kurs.	nein
CHECKOUT_UNAVAILABLE	Dieser Kurs kann im Widget noch nicht gebucht werden.	Bezahlkurs ohne bereiten Zahlungsanbieter.	Zahlungen im Workspace prüfen oder kostenlosen Kurs nutzen.	nein
PAYMENT_PROVIDER_INACTIVE	Für diesen Kurs ist gerade keine aktive Zahlung möglich. Bitte wende dich an den Kursanbieter oder versuche es später erneut.	Keine primäre Checkout-Verbindung.	Erste checkoutfähige Verbindung prüfen; Owner verbindet den Anbieter.	nein
CHECKOUT_STATE_UNAVAILABLE	Der sichere Checkout-Zustand konnte im Browser nicht gespeichert werden.	sessionStorage blockiert (Tracking-Prevention, privater Modus).	Speicher erlauben oder anderen Browser.	nein
PAYMENT_PROVIDER_UNAVAILABLE	Der Zahlungsanbieter ist gerade nicht erreichbar. Bitte versuche es erneut.	Anbieterstörung.	Später erneut versuchen.	ja
PAYMENT_STATUS_INVALID	Der Zahlungsstatus konnte nicht sicher geprüft werden.	Status-Token ungültig oder Checkout unbekannt.	Status im Widget erneut prüfen; nicht aus der Return-URL auf Erfolg schließen.	nein
PARTICIPANT_GRANT_INVALID	Die Konto-Freigabe ist abgelaufen. Melde dich bitte erneut an.	Grant älter als fünf Minuten oder bereits verbraucht.	Erneut anmelden, Gastbuchung bleibt möglich.	nein
RESPONSE_INVALID	Laden: Das Widget konnte nicht geladen werden. Bitte versuche es erneut. Buchung: Die Buchung konnte nicht abgeschlossen werden. Bitte versuche es erneut.	Unerwartete Antwort oder apiVersion ungleich 1.	Netzwerk prüfen; bei Dauerfehler Support mit Code kontaktieren.	ja

INTERNAL_ERROR und andere unbekannte Codes nutzen denselben Fallback-Text wie RESPONSE_INVALID und gelten als erneut versuchbar, wenn retryable im Event true ist.

Häufige Host-Probleme

Widget bleibt leer, kein Alert

script-src blockiert das Modul. Das Custom Element wird nie definiert. Höre auf error am Script-Tag und zeige eigenen Fallback.

Host-CSS färbt Buttons rot / riesige Schrift

Gewollt isoliert. Wenn interne Knoten die Host-Styles erben, ist das Script nicht das offizielle Modul. Siehe Isolationstest in apps/e2e/tests/widget-embed.spec.ts.

Widget zu schmal oder Karten untereinander

Container-Query ab 34 rem. Gib dem Element genug Breite oder akzeptiere die einspaltige Ansicht auf schmalen Spalten.

Teilnehmerkonto-Buttons ohne Fenster

Pop-up blockiert. Gastformular bleibt nutzbar. Origin muss in der Allowlist stehen; leere Allowlist deaktiviert die Kontobrücke.

Bezahlter Kurs nicht auswählbar

Manifest meldet paidCheckout: false. Im Widget steht „Online-Zahlung nicht verfügbar“. Zahlungsanbieter im Workspace prüfen.

Kompatibilität

• Vertrag: apiVersion 1. Inkompatible Änderungen brauchen eine neue Script-/API-Version.
• Browser: aktuelle Chrome-, Firefox-, Safari- und Edge-Versionen. Kein Internet Explorer.
• Shadow DOM, Custom Elements und ES-Module sind Pflicht. Constructable Stylesheets sind bevorzugt; ältere Browser fallen auf ein Style-Element im Shadow Root zurück.
• Mehrere Instanzen auf einer Seite sind unterstützt. Das Script nur einmal laden.

Diagnose ohne Secrets

Sicher nennbar: Event-code, phase, retryable, Key-Präfix und Key-Version aus dem Dashboard, Host-Origin, ob das Widget aktiv ist.

Nicht teilen: vollständiger Widget-Key, Hash, Name, E-Mail, Grant, Status-Token, Zahlungs-IDs.