Response.status — Eigenschaft · JavaScript-Referenz

Signatur

Response.status

Beschreibung

Die Eigenschaft status eines Response-Objekts gibt den HTTP-Statuscode zurück, den der Server gesendet hat. Das ist eine ganze Zahl, meist zwischen 200 und 599. Beispiele sind 200 (OK), 201 (Created), 204 (No Content), 404 (Not Found) oder 500 (Internal Server Error).

Wichtig: fetch() wird bei HTTP-Fehlercodes wie 404 oder 500 nicht abgelehnt. Das Promise wird nur bei Netzwerkfehlern, CORS-Verstößen oder einem Abbruch abgelehnt. Deshalb muss man status (oder ok) selbst prüfen, um Fehlerantworten zu erkennen und gezielt zu behandeln.

Oft reicht die Kurzform response.ok. Sie ist true, wenn status im Bereich 200–299 liegt. status selbst braucht man, wenn einzelne Codes unterschiedlich behandelt werden sollen, etwa 401 für eine erneute Anmeldung, 429 für Wiederholungen mit Wartezeit oder 204, wenn kein Body kommt.

Bei selbst erzeugten Antworten, etwa in einem Service Worker, legt man den Wert über das Optionsobjekt des Konstruktors fest: new Response(body, { status: 404 }). Ohne Angabe ist der Standardwert 200.

Rückgabewert

Typ

number

Beschreibung

Der HTTP-Statuscode als ganze Zahl (z. B. 200, 404). Bei opaken Antworten (type: "opaque" oder "opaqueredirect") und bei Response.error() ist der Wert 0.

Beispiele

Statuscode einer Anfrage prüfen

const response = await fetch('https://jsonplaceholder.typicode.com/posts/1');
console.log(response.status);     // numerischer Code
console.log(response.statusText); // Textbeschreibung (bei HTTP/2 oft leer)
console.log(response.ok);         // true bei 200–299

200 OK true

Verschiedene Statuscodes gezielt behandeln

const ladeBenutzer = async (id) => {
  const response = await fetch(`/api/users/${id}`);

  switch (response.status) {
    case 200:
      return response.json();
    case 204:
      return null; // kein Inhalt, response.json() würde fehlschlagen
    case 401:
      window.location.href = '/login';
      return null;
    case 404:
      throw new Error(`Benutzer ${id} nicht gefunden`);
    default:
      if (response.status >= 500) {
        throw new Error(`Serverfehler (${response.status})`);
      }
      throw new Error(`Unerwarteter Status: ${response.status}`);
  }
};

try {
  const user = await ladeBenutzer(42);
  console.log(user);
} catch (err) {
  console.error(err.message);
}

Benutzer 42 nicht gefunden // falls der Server 404 liefert

Bei 429/503 mit Wartezeit erneut versuchen

const fetchMitRetry = async (url, versuche = 3) => {
  for (let i = 0; i < versuche; i++) {
    const response = await fetch(url);
    if (response.status !== 429 && response.status !== 503) {
      return response;
    }
    // Retry-After-Header in Sekunden auswerten, sonst exponentiell warten
    const retryAfter = Number(response.headers.get('Retry-After')) || 2 ** i;
    console.log(`Status ${response.status}, neuer Versuch in ${retryAfter}s`);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('Zu viele Versuche');
};

const res = await fetchMitRetry('/api/daten');
console.log(res.status);

Status 429, neuer Versuch in 1s 200

Eigenen Status in einem Service Worker setzen

self.addEventListener('fetch', (event) => {
  if (new URL(event.request.url).pathname === '/api/offline-test') {
    const antwort = new Response(JSON.stringify({ fehler: 'offline' }), {
      status: 503,
      statusText: 'Service Unavailable',
      headers: { 'Content-Type': 'application/json' },
    });
    console.log(antwort.status); // 503
    event.respondWith(antwort);
  }
});

503

// Wichtig · Fallstricke

Kein automatischer Fehler: fetch() wird bei 4xx/5xx nicht abgelehnt. Prüfen Sie immer response.ok oder response.status, bevor Sie den Body verarbeiten.
Status 0: Bei mode: "no-cors" (opake Antwort), bei redirect: "manual" (opaqueredirect) und bei Response.error() ist status 0. Der echte Code ist aus Sicherheitsgründen nicht einsehbar.
Weiterleitungen: Mit dem Standardwert redirect: "follow" sieht man nie 301/302, sondern den Status des endgültigen Ziels. Ob weitergeleitet wurde, zeigt response.redirected.
Schreibgeschützt: Eine Zuweisung an response.status wird ignoriert und wirft im Strict Mode einen TypeError. Einen anderen Status setzt man nur über new Response(body, { status }).
Gültiger Wertebereich im Konstruktor: status muss zwischen 200 und 599 liegen, sonst wirft der Konstruktor einen RangeError. Bei 101, 103, 204, 205 und 304 ist kein Body erlaubt (TypeError).
statusText: Unter HTTP/2 und HTTP/3 ist statusText meist leer. Verlassen Sie sich deshalb auf den numerischen status.
Kompatibilität: Wird von allen modernen Browsern unterstützt, ebenso von Web Workern und Service Workern, Node.js ab Version 18 (globales fetch), Deno und Bun.

Siehe auch

Response Response.ok Response.redirected Response.type Response.error()