RTCErrorEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCErrorEvent extends Event

Beschreibung

RTCErrorEvent ist der Ereignistyp, den WebRTC-Objekte beim Ereignis error auslösen, vor allem RTCDataChannel und RTCDtlsTransport. Es erbt von Event und hat nur eine eigene Eigenschaft, nämlich error (schreibgeschützt). Sie enthält ein RTCError-Objekt.

RTCError erweitert DOMException und liefert WebRTC-spezifische Diagnosedaten:

errorDetail: Fehlerkategorie, z. B. "data-channel-failure", "dtls-failure", "fingerprint-failure", "sctp-failure", "sdp-syntax-error", "hardware-encoder-error" oder "hardware-encoder-not-available".
sctpCauseCode: SCTP-Fehlercode bei "sctp-failure", sonst null.
sdpLineNumber: fehlerhafte SDP-Zeile bei "sdp-syntax-error", sonst null.
receivedAlert / sentAlert: DTLS-Alert-Codes bei "dtls-failure", sonst null.

Du brauchst das Ereignis, wenn du Verbindungsprobleme in Echtzeitanwendungen erkennen, protokollieren oder beheben willst, etwa bei abgebrochenen Datenkanälen oder gescheiterten DTLS-Handshakes. Den Listener registrierst du mit addEventListener("error", …) oder über die Eigenschaft onerror des jeweiligen Objekts. Selbst erzeugen musst du das Ereignis nur selten, etwa in Tests oder Polyfills. Dafür gibt es den Konstruktor new RTCErrorEvent(type, { error }).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Ereignisses, in der Praxis immer `"error"`.
$options Pflicht	{ error: RTCError, bubbles?: boolean, cancelable?: boolean, composed?: boolean }		Konstruktor-Parameter: Das Objekt muss die Eigenschaft `error` mit einer `RTCError`-Instanz enthalten. Dazu kommen die üblichen `EventInit`-Optionen.

Rückgabewert

Typ

RTCErrorEvent

Beschreibung

Der Konstruktor liefert eine neue RTCErrorEvent-Instanz. Ihre Eigenschaft error (RTCError) enthält die Fehlerdetails.

Beispiele

Fehler eines RTCDataChannel mit addEventListener auswerten

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel('chat');

channel.addEventListener('error', (event) => {
  const err = event.error; // RTCError
  console.error(`DataChannel-Fehler: ${err.message}`);
  console.log('Kategorie:', err.errorDetail);

  if (err.errorDetail === 'sctp-failure') {
    console.log('SCTP-Code:', err.sctpCauseCode);
  }
});

DataChannel-Fehler: Transport channel closed Kategorie: sctp-failure SCTP-Code: 12

Handler über die onerror-Eigenschaft setzen und wieder entfernen

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel('dateien');

channel.onerror = (event) => {
  if (event instanceof RTCErrorEvent) {
    reportToServer({
      detail: event.error.errorDetail,
      message: event.error.message
    });
  }
};

function reportToServer(data) {
  navigator.sendBeacon('/api/rtc-errors', JSON.stringify(data));
}

// Später, z. B. beim Aufräumen:
// channel.onerror = null;

DTLS-Fehler am Transport erkennen

const pc = new RTCPeerConnection();

pc.addEventListener('connectionstatechange', () => {
  const [sender] = pc.getSenders();
  const dtls = sender?.transport;
  if (!dtls || dtls.onerror) return;

  dtls.onerror = (event) => {
    const { errorDetail, receivedAlert, sentAlert } = event.error;
    console.warn('DTLS-Problem:', errorDetail, { receivedAlert, sentAlert });
  };
});

DTLS-Problem: dtls-failure { receivedAlert: 40, sentAlert: null }

RTCErrorEvent für Tests selbst erzeugen

const error = new RTCError(
  { errorDetail: 'data-channel-failure' },
  'Simulierter Kanalabbruch'
);
const event = new RTCErrorEvent('error', { error });

const target = new EventTarget();
target.addEventListener('error', (e) => {
  console.log(e.type, e.error.errorDetail, e.error.message);
});
target.dispatchEvent(event);

error data-channel-failure Simulierter Kanalabbruch

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser (ab Version 74) und Safari unterstützen RTCErrorEvent und RTCError. In Firefox kann das error-Ereignis je nach Version ein einfaches Event ohne Eigenschaft error sein. Prüfe daher defensiv, etwa mit event.error?.errorDetail oder 'RTCErrorEvent' in window.
Viele WebRTC-Fehler kommen nicht als Ereignis an, sondern als abgelehntes Promise, z. B. bei setRemoteDescription() oder createOffer(). Die fängst du mit try/catch ab. RTCErrorEvent gilt nur für asynchron auftretende Transport- und Kanalfehler.
Die Eigenschaften sctpCauseCode, sdpLineNumber, receivedAlert und sentAlert sind nur bei der passenden errorDetail-Kategorie gefüllt, sonst null.
Die ältere Eigenschaft httpRequestStatusCode wurde aus der Spezifikation entfernt. Verlass dich nicht darauf.
Nach einem Fehler wird ein RTCDataChannel meist geschlossen. Reagiere zusätzlich auf das Ereignis close, wenn du die Verbindung automatisch neu aufbauen willst.
Der Konstruktor wirft einen TypeError, wenn im Optionsobjekt error fehlt.

Siehe auch

Event SensorErrorEvent ErrorEvent RTCTrackEvent RTCError