Response.json() — Methode · JavaScript-Referenz

Signatur

Response.json(data, options)

Beschreibung

Die statische Methode Response.json() ist eine Fabrikmethode: Sie serialisiert den übergebenen Wert intern mit JSON.stringify(), setzt das Ergebnis als Body einer neuen Response und ergänzt automatisch den Header Content-Type: application/json. Damit entfällt der sonst übliche Umweg über new Response(JSON.stringify(data), { headers: … }).

Gebraucht wird sie vor allem dort, wo JavaScript selbst Antworten erzeugt: in Service Workern (z. B. im fetch-Event für Offline-Antworten oder Mock-APIs), in serverseitigen Laufzeitumgebungen mit Fetch-API-Standard wie Node.js, Deno, Bun, Cloudflare Workers oder in Route-Handlern von Frameworks wie Next.js, Remix und Hono sowie in Tests, wenn man fetch durch eine Attrappe ersetzt.

Wichtig: Man darf sie nicht mit der Instanzmethode Response.prototype.json() verwechseln. Die Instanzmethode liest den Body einer vorhandenen Antwort und wandelt ihn in ein JavaScript-Objekt um (Rückgabe: Promise). Die statische Methode erzeugt dagegen synchron eine neue Antwort.

Parameter

Name	Typ	Default	Beschreibung
$data Pflicht	any (JSON-serialisierbar)		Der Wert, der mit `JSON.stringify()` in den Body geschrieben wird, z. B. ein Objekt, Array, eine Zeichenkette, Zahl, ein boolescher Wert oder `null`.
$options	object	{}	Optionen wie beim `Response`-Konstruktor: `status` (`number`, Standard `200`) `statusText` (`string`, Standard `""`) `headers` (`Headers` \| `object` \| `Array`): zusätzliche Header. Ein hier angegebener `Content-Type` ersetzt den Standardwert.

Beispiele

Einfache JSON-Antwort erzeugen und wieder auslesen

const res = Response.json({ id: 42, name: 'Anna' });

console.log(res.status);                      // 200
console.log(res.headers.get('Content-Type')); // application/json

// Instanzmethode json() liest den Body wieder aus
const daten = await res.json();
console.log(daten.name);

200 application/json Anna

API-Route mit Statuscode und eigenen Headern (Node.js, Deno, Bun, Edge)

const benutzer = new Map([[1, { id: 1, name: 'Anna' }]]);

const handleRequest = (request) => {
  const url = new URL(request.url);
  const id = Number(url.searchParams.get('id'));
  const user = benutzer.get(id);

  if (!user) {
    return Response.json(
      { error: 'Benutzer nicht gefunden' },
      { status: 404, headers: { 'Cache-Control': 'no-store' } }
    );
  }
  return Response.json(user);
};

const res = handleRequest(new Request('https://api.example.com/user?id=7'));
console.log(res.status, await res.json());

404 { error: 'Benutzer nicht gefunden' }

Service Worker: Offline-Ersatzantwort für eine API

// sw.js
self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);
  if (!url.pathname.startsWith('/api/')) return;

  event.respondWith(
    fetch(event.request).catch(() =>
      Response.json(
        { offline: true, items: [] },
        { status: 503, statusText: 'Service Unavailable' }
      )
    )
  );
});

fetch in Tests durch eine Attrappe ersetzen

globalThis.fetch = async (url) =>
  Response.json([{ id: 1, titel: 'Test-Artikel' }]);

const ladeArtikel = async () => {
  const res = await fetch('/api/artikel');
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
};

console.log(await ladeArtikel());

[ { id: 1, titel: 'Test-Artikel' } ]

// Wichtig · Fallstricke

Statisch oder Instanzmethode: Response.json(data) erzeugt eine Antwort, response.json() liest eine aus. Schreibt man versehentlich await Response.json() ohne Argument, entsteht eine Antwort mit dem Body undefined. Das ist in der Regel ein Fehler.
Serialisierungsfehler: Kann JSON.stringify() den Wert nicht verarbeiten, etwa bei zirkulären Referenzen oder BigInt, wirft die Methode synchron einen TypeError. Ist der Wert gar nicht serialisierbar (z. B. undefined oder eine Funktion), gibt es ebenfalls einen TypeError. Wie bei JSON.stringify werden Date-Objekte zu Zeichenketten; Map und Set werden zu {}.
Ungültige Optionen: Ein status außerhalb von 200–599 löst einen RangeError aus. Die Statuscodes 101, 204, 205 und 304 dürfen keinen Body haben, deshalb wirft die Methode hier einen TypeError.
Kompatibilität: Erst seit 2023 in allen großen Browsern verfügbar (Chrome/Edge 105, Firefox 115, Safari 17), in Node.js ab Version 18. Für ältere Umgebungen bleibt new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } }) als Ausweichlösung.
Sicherheit: Keine vertraulichen Daten wie Passwort-Hashes oder interne IDs ungefiltert zurückgeben. Die Methode serialisiert immer das gesamte Objekt, daher vorher gezielt nur die benötigten Felder auswählen.

Siehe auch

Response Response.error() Response.redirect() JSON.stringify() Headers