new QuotaExceededError() — Methode · JavaScript-Referenz

Signatur

new QuotaExceededError(message, options)

Beschreibung

Der Konstruktor QuotaExceededError() erzeugt eine Instanz der gleichnamigen Klasse, die von DOMException erbt. Früher war „QuotaExceededError“ nur der name einer gewöhnlichen DOMException. Seit der Neufassung im WebIDL-Standard ist es eine eigene Unterklasse mit den zusätzlichen Eigenschaften quota und requested.

Browser-APIs wie localStorage, IndexedDB, die Cache API oder crypto.getRandomValues() werfen diesen Fehler selbst, wenn ein Limit überschritten wird. Den Konstruktor brauchst du vor allem dann, wenn deine eigene Bibliothek (z. B. ein Speicher-Wrapper, ein Upload-Limit oder ein Mock in Tests) denselben, standardkonformen Fehlertyp werfen soll. Aufrufender Code kann ihn dann einheitlich mit instanceof oder über err.name erkennen.

Die erzeugte Instanz hat immer name === "QuotaExceededError" und den veralteten Code code === 22. Werden quota oder requested nicht übergeben, sind die Eigenschaften null.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Menschenlesbare Fehlerbeschreibung, die später in `err.message` steht.
$options	{ quota?: number, requested?: number }	{}	Optionales Objekt mit Zusatzangaben. `quota`: das geltende Limit (z. B. in Bytes). `requested`: die angeforderte Menge. Beide Werte müssen nicht-negative Zahlen sein.
$options.quota	number		Maximal erlaubte Menge. Ohne Angabe ist `err.quota` gleich `null`.
$options.requested	number		Angeforderte Menge. Werden beide Werte angegeben, darf `requested` nicht kleiner als `quota` sein.

Rückgabewert

Typ

QuotaExceededError

Beschreibung

Ein neues QuotaExceededError-Objekt (Unterklasse von DOMException) mit name, message, code (22), quota und requested.

Beispiele

Fehler erzeugen und Eigenschaften lesen

const err = new QuotaExceededError('Upload-Limit überschritten', {
  quota: 10_000_000,
  requested: 12_500_000,
});

console.log(err.name);            // Fehlername
console.log(err.message);
console.log(err.quota, err.requested);
console.log(err instanceof DOMException);
console.log(err.code);

QuotaExceededError Upload-Limit überschritten 10000000 12500000 true 22

Eigener Speicher-Wrapper mit Größenlimit

const MAX_BYTES = 1024;

const saveDraft = (key, value) => {
  const json = JSON.stringify(value);
  const size = new Blob([json]).size;
  if (size > MAX_BYTES) {
    throw new QuotaExceededError(`Entwurf zu groß (${size} Bytes)`, {
      quota: MAX_BYTES,
      requested: size,
    });
  }
  localStorage.setItem(key, json);
};

try {
  saveDraft('draft', { text: 'x'.repeat(2000) });
} catch (err) {
  if (err instanceof QuotaExceededError) {
    console.warn(`Limit: ${err.quota}, angefordert: ${err.requested}`);
  }
}

Limit: 1024, angefordert: 2012

Browser-kompatibles Erkennen von Kontingentfehlern

// Funktioniert in alten Browsern (DOMException mit name) und in neuen (Unterklasse)
const isQuotaError = (err) =>
  err instanceof DOMException &&
  (err.name === 'QuotaExceededError' || err.code === 22);

try {
  localStorage.setItem('big', 'x'.repeat(50 * 1024 * 1024));
} catch (err) {
  if (isQuotaError(err)) {
    console.log('Speicher voll – alte Einträge werden gelöscht.');
    localStorage.removeItem('cache');
  } else {
    throw err;
  }
}

Speicher voll – alte Einträge werden gelöscht.

Ungültige Optionen führen zu RangeError

try {
  new QuotaExceededError('Test', { quota: 100, requested: 50 });
} catch (e) {
  console.log(e.name);
}

try {
  new QuotaExceededError('Test', { quota: -1 });
} catch (e) {
  console.log(e.name);
}

RangeError RangeError

// Wichtig · Fallstricke

Neue API: Der Konstruktor ist erst seit 2025 in Browsern verfügbar. Prüfe vorher mit typeof QuotaExceededError === 'function'. Als Fallback eignet sich new DOMException(message, 'QuotaExceededError'), das allerdings keine Eigenschaften quota und requested hat.
Erkennung: In älteren Browsern ist ein Kontingentfehler keine Instanz von QuotaExceededError. Für portablen Code solltest du deshalb err.name === 'QuotaExceededError' prüfen statt instanceof. Sehr alte Firefox-Versionen verwendeten zusätzlich den Namen NS_ERROR_DOM_QUOTA_REACHED.
Validierung: Negative Werte für quota oder requested lösen einen RangeError aus. Dasselbe gilt, wenn requested kleiner als quota ist.
Browser füllen quota und requested oft nicht aus, etwa bei localStorage. Rechne also immer mit null.
Der Wert von code (22) ist veraltet. Verwende ihn nur für die Abwärtskompatibilität.
Im privaten Modus mancher Browser (z. B. älteres Safari) ist das Speicherkontingent 0. Dann schlägt schon das erste setItem() mit diesem Fehler fehl.

Siehe auch

new FederatedCredential() new BarcodeDetector() new GPUOutOfMemoryError() new GPUPipelineError() new RTCError()