RTCError — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCError extends DOMException

Beschreibung

RTCError beschreibt Fehler, die bei WebRTC-Operationen auftreten, zum Beispiel beim Aushandeln der Verbindung (SDP), beim DTLS-Handshake oder beim Transport über einen RTCDataChannel (SCTP). Die Klasse erweitert DOMException. Deshalb gibt es wie gewohnt name (immer "OperationError") und message. Dazu kommen Eigenschaften, mit denen man die Fehlerursache genau bestimmen kann.

Meist bekommt man ein RTCError über das error-Ereignis eines RTCDataChannel. Das Ereignis ist ein RTCErrorEvent, und dessen Eigenschaft event.error enthält das RTCError-Objekt. Browser können es auch als Ablehnungsgrund eines Promise liefern, etwa bei setRemoteDescription().

Wichtige Eigenschaften (alle nur lesbar):

errorDetail: Fehlerkategorie als String: "data-channel-failure", "dtls-failure", "fingerprint-failure", "sctp-failure", "sdp-syntax-error", "hardware-encoder-not-available" oder "hardware-encoder-error".
sdpLineNumber: Zeilennummer im SDP, in der ein Syntaxfehler gefunden wurde, sonst null.
sctpCauseCode: SCTP-Fehlercode nach RFC 4960, wenn errorDetail den Wert "sctp-failure" hat, sonst null.
receivedAlert / sentAlert: Code der empfangenen bzw. gesendeten DTLS-Warnung, wenn errorDetail den Wert "dtls-failure" hat, sonst null.
httpRequestStatusCode: HTTP-Statuscode bei bestimmten Fehlern, die mit der Identitätsprüfung zu tun haben (in Browsern kaum umgesetzt).

Sinnvoll ist RTCError vor allem für eine genaue Fehlerbehandlung und fürs Protokollieren (Telemetrie). So kann man zum Beispiel einen abgebrochenen Datenkanal von einem fehlerhaften SDP-Angebot unterscheiden und passend reagieren, etwa mit einem Neuaufbau der Verbindung oder einer Meldung an den Nutzer.

Parameter

Name	Typ	Default	Beschreibung
$init Pflicht	RTCErrorInit		Objekt mit den Fehlerdetails. Pflichtfeld ist `errorDetail`. Optional sind `sdpLineNumber`, `sctpCauseCode`, `receivedAlert`, `sentAlert` und `httpRequestStatusCode` (jeweils `number`).
$message	string	""	Lesbare Fehlerbeschreibung, landet in `error.message`.

Rückgabewert

Typ

RTCError

Beschreibung

Eine neue RTCError-Instanz (bei new RTCError(init, message)) mit name === "OperationError".

Beispiele

Fehler eines RTCDataChannel auswerten

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

const onChannelError = (event) => {
  const err = event.error; // RTCError
  console.error(`${err.name}: ${err.message}`);

  switch (err.errorDetail) {
    case 'sctp-failure':
      console.warn('SCTP-Fehlercode:', err.sctpCauseCode);
      break;
    case 'dtls-failure':
      console.warn('DTLS-Warnung empfangen/gesendet:', err.receivedAlert, err.sentAlert);
      break;
    case 'data-channel-failure':
      console.warn('Datenkanal konnte nicht geöffnet werden');
      break;
    default:
      console.warn('Sonstiger Fehler:', err.errorDetail);
  }
};

channel.addEventListener('error', onChannelError);
// Alternativ: channel.onerror = onChannelError;

OperationError: ... SCTP-Fehlercode: 12 (Beispiel: Abbruch durch den Nutzer)

RTCError selbst erzeugen (z. B. für Tests)

const err = new RTCError(
  { errorDetail: 'sdp-syntax-error', sdpLineNumber: 7 },
  'Ungültige a=rtpmap-Zeile'
);

console.log(err instanceof DOMException); // true
console.log(err.name);          // "OperationError"
console.log(err.errorDetail);   // "sdp-syntax-error"
console.log(err.sdpLineNumber); // 7
console.log(err.sctpCauseCode); // null

true OperationError sdp-syntax-error 7 null

Ablehnung von setRemoteDescription robust behandeln

const applyAnswer = async (pc, answer) => {
  try {
    await pc.setRemoteDescription(answer);
  } catch (err) {
    // Feature-Erkennung: nicht jeder Browser kennt RTCError
    if (typeof RTCError !== 'undefined' && err instanceof RTCError) {
      if (err.errorDetail === 'sdp-syntax-error') {
        console.error(`SDP-Fehler in Zeile ${err.sdpLineNumber}`);
      } else {
        console.error('WebRTC-Fehler:', err.errorDetail);
      }
    } else {
      // Fallback: gewöhnliche DOMException (z. B. InvalidAccessError)
      console.error(`${err.name}: ${err.message}`);
    }
    throw err;
  }
};

// Wichtig · Fallstricke

Browser-Kompatibilität: RTCError und RTCErrorEvent gibt es in Chromium-Browsern (ab Version 74) und in Safari (ab 15.4). Firefox unterstützt beide Schnittstellen derzeit nicht. Dort melden Datenkanäle Fehler als einfaches Event ohne error-Eigenschaft. Prüfe deshalb vorher mit typeof RTCError !== 'undefined' und greife optional zu: event.error?.errorDetail.

Viele WebRTC-Methoden lehnen ihr Promise nicht mit RTCError ab, sondern mit einer gewöhnlichen DOMException (z. B. InvalidStateError oder InvalidAccessError). Verlasse dich also nicht darauf, dass errorDetail vorhanden ist.
name ist immer "OperationError". Die eigentliche Ursache steht in errorDetail, nicht in name.
Eigenschaften, die für die jeweilige Fehlerart nicht gelten, haben den Wert null (nicht undefined).
Die Werte "hardware-encoder-*" hängen vom Browser ab und kommen in der Praxis selten vor.
Sicherheit: message kann technische Details enthalten, etwa Ausschnitte aus dem SDP. Zeige sie Endnutzern nicht ungefiltert an.

Siehe auch

DOMError GPUError IDBCursor MediaError RTCErrorEvent