DOMException.code — Eigenschaft · JavaScript-Referenz

Signatur

DOMException.code

Beschreibung

Die schreibgeschützte Eigenschaft code einer DOMException liefert eine Zahl, die einer der alten Fehlercode-Konstanten entspricht, z. B. DOMException.NOT_FOUND_ERR (8) oder DOMException.ABORT_ERR (20). Gibt es für den Fehlernamen keinen alten Code, ist der Wert 0.

Diese Codes stammen aus früheren DOM-Spezifikationen. Heute sind sie veraltet. Ein Fehler wird stattdessen über die Eigenschaft name erkannt, also über Zeichenketten wie "NotFoundError", "AbortError" oder "QuotaExceededError". Neuere Fehlertypen wie "NotAllowedError", "NotReadableError", "OperationError" oder "ConstraintError" haben keinen eigenen Code und liefern deshalb immer 0.

code braucht man nur noch, wenn man alten Code pflegt, der Fehler über Zahlen unterscheidet, oder wenn man Bibliotheken nutzt, die das tun. In neuem Code sollte man immer error.name abfragen.

Wichtige Zuordnungen (Name → Code): IndexSizeError → 1, HierarchyRequestError → 3, WrongDocumentError → 4, InvalidCharacterError → 5, NoModificationAllowedError → 7, NotFoundError → 8, NotSupportedError → 9, InvalidStateError → 11, SyntaxError → 12, InvalidModificationError → 13, NamespaceError → 14, InvalidAccessError → 15, TypeMismatchError → 17, SecurityError → 18, NetworkError → 19, AbortError → 20, URLMismatchError → 21, QuotaExceededError → 22, TimeoutError → 23, InvalidNodeTypeError → 24, DataCloneError → 25.

Rückgabewert

Typ

number

Beschreibung

Ganzzahliger alter Fehlercode (1–25) passend zum name der Ausnahme, oder 0, wenn es für diesen Namen keinen alten Code gibt.

Beispiele

Code eines DOM-Fehlers auslesen

try {
  // Ungültiger Tag-Name löst InvalidCharacterError aus
  document.createElement('1ungültig');
} catch (err) {
  console.log(err instanceof DOMException);
  console.log(err.name);
  console.log(err.code);
  console.log(err.code === DOMException.INVALID_CHARACTER_ERR);
}

true InvalidCharacterError 5 true

Selbst erzeugte DOMException: Code wird aus dem Namen abgeleitet

const bekannt = new DOMException('Element fehlt', 'NotFoundError');
const modern = new DOMException('Zugriff verweigert', 'NotAllowedError');
const eigen = new DOMException('Etwas ging schief', 'MeinFehler');

console.log(bekannt.code); // alter Code vorhanden
console.log(modern.code);  // neuer Name, kein alter Code
console.log(eigen.code);   // eigener Name, kein Code

8 0 0

Abbruch per AbortController: besser name statt code prüfen

const controller = new AbortController();

const laden = async () => {
  try {
    await fetch('https://example.com/grosse-datei', { signal: controller.signal });
  } catch (err) {
    // Empfohlen: über den Namen prüfen
    if (err.name === 'AbortError') {
      console.log('Abgebrochen, Code:', err.code);
    } else {
      throw err;
    }
  }
};

laden();
controller.abort();

Abgebrochen, Code: 20

Alten Code-basierten Fehlerzweig umstellen

// Früher üblich:
const istKontingentVollAlt = (err) => err.code === DOMException.QUOTA_EXCEEDED_ERR;

// Heute empfohlen:
const istKontingentVoll = (err) =>
  err instanceof DOMException && err.name === 'QuotaExceededError';

const fehler = new DOMException('Speicher voll', 'QuotaExceededError');
console.log(istKontingentVollAlt(fehler), istKontingentVoll(fehler));

true true

// Wichtig · Fallstricke

Veraltet: code gibt es nur noch aus Kompatibilitätsgründen. Für neue Fehlertypen kommt immer 0 zurück. Unterscheide Fehler deshalb über err.name.
Schreibgeschützt: Eine Zuweisung wie err.code = 5 hat keine Wirkung und wirft im strikten Modus einen TypeError. Der Code folgt immer aus dem name, der dem Konstruktor übergeben wurde.
Codes wie 2 (DOMSTRING_SIZE_ERR), 6 (NO_DATA_ALLOWED_ERR), 10 (INUSE_ATTRIBUTE_ERR) und 16 (VALIDATION_ERR) sind historisch. Zu ihnen gibt es keinen Fehlernamen mehr, sie werden also nie zurückgegeben.
Die Konstanten wie DOMException.NOT_FOUND_ERR gibt es sowohl am Konstruktor als auch am Prototyp.
Nicht jeder abgefangene Fehler ist eine DOMException. Ein TypeError oder RangeError hat kein code, dort ist der Wert undefined. Prüfe vorher mit instanceof DOMException.
Kompatibilität: Die Eigenschaft wird von allen modernen Browsern, von Node.js (ab 17 global) und von Deno unterstützt.

Siehe auch

DOMException DOMException.name DOMException.message Error MediaError.code