Response.statusText — Eigenschaft · JavaScript-Referenz

Signatur

Response.statusText

Beschreibung

Die schreibgeschützte Eigenschaft statusText der Response-Schnittstelle enthält die Statusnachricht (englisch reason phrase), die der Server zusammen mit dem Statuscode in Response.status gesendet hat. Bei 200 ist das in der Regel "OK", bei 404 "Not Found".

Die Eigenschaft ist vor allem für Protokollierung und Fehlermeldungen nützlich, etwa wenn man nach einem fehlgeschlagenen fetch()-Aufruf eine lesbare Meldung ausgeben möchte. Für die eigentliche Programmlogik sollte man sich immer auf status oder ok stützen, nicht auf den Text.

Der Wert kommt direkt vom Server und ist nicht vom Browser aus dem Statuscode abgeleitet. Bei HTTP/2 und HTTP/3 gibt es gar keine Statusnachricht mehr im Protokoll. Dort ist statusText eine leere Zeichenkette "". Beim Erzeugen eigener Antworten mit new Response(body, { status, statusText }) lässt sich der Wert frei festlegen, etwa in Service Workern oder Tests.

Rückgabewert

Typ

string

Beschreibung

Die Statusnachricht des Servers, z. B. "OK", "Not Found" oder "Internal Server Error". Ohne Nachricht (z. B. bei HTTP/2) ist der Wert "".

Beispiele

Statuscode und Statustext nach fetch() ausgeben

const res = await fetch('https://jsonplaceholder.typicode.com/posts/1');
console.log(res.status, res.statusText);

200 OK (bei HTTP/2-Verbindungen: 200 "")

Aussagekräftige Fehlermeldung mit Rückfall bei leerem statusText

const fetchJson = async (url) => {
  const res = await fetch(url);
  if (!res.ok) {
    // statusText kann bei HTTP/2 leer sein, deshalb einen Ersatztext verwenden
    const text = res.statusText || 'Unbekannter Fehler';
    throw new Error(`HTTP ${res.status}: ${text}`);
  }
  return res.json();
};

try {
  await fetchJson('https://httpbin.org/status/404');
} catch (err) {
  console.error(err.message);
}

HTTP 404: NOT FOUND (oder "HTTP 404: Unbekannter Fehler" bei HTTP/2)

Eigene Response mit statusText erzeugen (z. B. im Service Worker)

const offline = new Response(JSON.stringify({ error: 'offline' }), {
  status: 503,
  statusText: 'Service Unavailable',
  headers: { 'Content-Type': 'application/json' }
});

console.log(offline.status, offline.statusText);
console.log(offline.ok);

503 Service Unavailable false

Standardwert bei new Response() ohne Optionen

const res = new Response('Hallo');
console.log(JSON.stringify(res.statusText));
console.log(res.status);

"" 200

// Wichtig · Fallstricke

HTTP/2 und HTTP/3: Diese Protokolle übertragen keine Statusnachricht. statusText ist dort immer "". Deshalb nie per Textvergleich (statusText === 'OK') prüfen, sondern status oder ok verwenden.
Vom Server bestimmt: Der Text kann von der üblichen Formulierung abweichen, etwa "NOT FOUND" statt "Not Found", oder ganz eigene Texte enthalten.
Opake Antworten: Bei mode: 'no-cors' (type === 'opaque') und bei Netzwerkfehler-Antworten (Response.error()) ist statusText leer und status ist 0.
Konstruktor: Ein statusText mit ungültigen Zeichen (z. B. Zeilenumbrüchen) löst in new Response() einen TypeError aus. Die Eigenschaft selbst ist schreibgeschützt: Eine Zuweisung wird ohne Fehlermeldung ignoriert bzw. löst im Strict Mode einen TypeError aus.
Kompatibilität: Wird von allen modernen Browsern, Web Workern, Service Workern, Deno und Node.js ab Version 18 (globales fetch) unterstützt.

Siehe auch

Response.status Response.ok Response Response.headers PaymentResponse.payerEmail