new RTCError() — Methode · JavaScript-Referenz

Signatur

new RTCError(options, message)

Beschreibung

Der Konstruktor RTCError() erzeugt eine neue Instanz von RTCError. Die Schnittstelle erbt von DOMException und ergänzt sie um WebRTC-spezifische Felder. Dazu gehören errorDetail, sdpLineNumber, httpRequestStatusCode, sctpCauseCode, receivedAlert und sentAlert. Die Eigenschaft name einer solchen Instanz ist immer "OperationError".

Normalerweise erzeugt der Browser RTCError-Objekte selbst. Du bekommst sie zum Beispiel über die Eigenschaft error eines RTCErrorEvent, das bei einem RTCDataChannel ausgelöst wird. Auch abgelehnte Promises von setRemoteDescription() können ein RTCError liefern.

Selbst ruft man den Konstruktor vor allem in diesen Fällen auf:

in Tests und Mocks, um echte WebRTC-Fehler nachzustellen,
in Wrapper-Bibliotheken, die eigene Fehler im gleichen Format wie der Browser melden wollen,
in Polyfills und Adaptern.

Das Feld errorDetail in options ist Pflicht. Es gibt an, zu welcher Fehlerkategorie der Fehler gehört.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object (RTCErrorInit)		Objekt mit den Fehlereigenschaften. Pflicht ist `errorDetail`. Erlaubte Werte sind `"data-channel-failure"`, `"dtls-failure"`, `"fingerprint-failure"`, `"sctp-failure"`, `"sdp-syntax-error"`, `"hardware-encoder-not-available"` und `"hardware-encoder-error"`. Optional sind `sdpLineNumber`, `httpRequestStatusCode`, `sctpCauseCode`, `receivedAlert` und `sentAlert` (jeweils `number`). Sie sind nur für bestimmte `errorDetail`-Werte sinnvoll.
$message	string	""	Lesbare Fehlermeldung. Sie steht danach in `error.message`.

Rückgabewert

Typ

RTCError

Beschreibung

Ein neues RTCError-Objekt mit name === "OperationError". Die übergebenen Optionen sind als schreibgeschützte Eigenschaften verfügbar. Nicht gesetzte Zahlenfelder haben den Wert null.

Beispiele

RTCError für einen SDP-Syntaxfehler erzeugen

const err = new RTCError(
  { errorDetail: 'sdp-syntax-error', sdpLineNumber: 12 },
  'Ungültige a=fingerprint-Zeile im Remote-SDP'
);

console.log(err.name);          // OperationError
console.log(err.errorDetail);   // sdp-syntax-error
console.log(err.sdpLineNumber); // 12
console.log(err.message);
console.log(err instanceof DOMException); // true

OperationError sdp-syntax-error 12 Ungültige a=fingerprint-Zeile im Remote-SDP true

DataChannel-Fehler in einem Test simulieren

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

channel.addEventListener('error', (event) => {
  const { error } = event;
  if (error.errorDetail === 'sctp-failure') {
    console.warn(`SCTP-Fehler, Cause-Code: ${error.sctpCauseCode}`);
  }
});

// Fehler künstlich auslösen (z. B. in einem Unit-Test)
const fakeError = new RTCError(
  { errorDetail: 'sctp-failure', sctpCauseCode: 12 },
  'User-initiated abort'
);
channel.dispatchEvent(new RTCErrorEvent('error', { error: fakeError }));

SCTP-Fehler, Cause-Code: 12

Feature-Erkennung mit Rückfall auf DOMException

const createRtcError = (detail, message) => {
  if (typeof RTCError === 'function') {
    return new RTCError({ errorDetail: detail }, message);
  }
  // Rückfall z. B. für Firefox
  const e = new DOMException(message, 'OperationError');
  e.errorDetail = detail;
  return e;
};

const err = createRtcError('dtls-failure', 'DTLS-Handshake fehlgeschlagen');
console.log(err.name, err.errorDetail);

OperationError dtls-failure

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-basierte Browser (Chrome, Edge, Opera) und Safari unterstützen RTCError. Firefox implementiert die Schnittstelle bislang nicht. Prüfe deshalb vorher mit typeof RTCError === 'function', ob sie verfügbar ist.
Fehlt errorDetail oder ist der Wert ungültig, wirft der Konstruktor einen TypeError.
Achte auf die Reihenfolge der Argumente: Anders als bei DOMException kommt das Options-Objekt zuerst und die Meldung danach.
name ist immer "OperationError" und lässt sich nicht ändern. Unterscheide Fehler daher über errorDetail.
Die Zusatzfelder sind nur bei passendem errorDetail aussagekräftig: sdpLineNumber bei sdp-syntax-error, sctpCauseCode bei sctp-failure, receivedAlert/sentAlert bei dtls-failure.

Siehe auch

RTCError RTCErrorEvent DOMException RTCDataChannel RTCPeerConnection new CSSSkewX()