📦 Response Processing and Handling

The Response Object

Every fetch resolves to a Response. It's a structured view of what the server sent back, split into three areas: status (did it work?), headers (metadata about the reply), and the body (the actual payload).

💡 An analogy: A response is like a package on your doorstep. The tracking status tells you it arrived and whether delivery succeeded (status/ok). The shipping label lists the sender, weight, and contents type (headers). And inside is the thing you actually ordered — which you unwrap in whatever way suits it (json(), blob(), …).

Status Properties

Before touching the body, inspect the status. These read-only properties tell you how the request went:

const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');

console.log(response.status);     // 200
console.log(response.statusText); // "OK"
console.log(response.ok);         // true
console.log(response.url);        // the final URL
console.log(response.redirected); // false

Reading Headers

Response headers arrive as a Headers object with a Map-like interface. Header names are case-insensitive.

const response = await fetch('https://api.example.com/data');

// Look up individual headers
response.headers.has('Content-Type');        // true / false
response.headers.get('Content-Type');        // "application/json; charset=utf-8"

// Iterate over every header
for (const [name, value] of response.headers.entries()) {
  console.log(`${name}: ${value}`);
}

Body Processing Methods

The body is a stream. You turn it into usable data by calling one of the reader methods — each returns a promise and consumes the stream once.

// JSON API response
const users = await (await fetch('/api/users')).json();

// Plain text or HTML
const html = await (await fetch('/page.html')).text();

// Binary — image, PDF, etc.
const blob = await (await fetch('/logo.png')).blob();
imgEl.src = URL.createObjectURL(blob);

Routing by Content-Type

When you don't know the format in advance, inspect the header and branch:

async function readByType(response) {
  const type = response.headers.get('Content-Type') || '';
  if (type.includes('application/json')) return response.json();
  if (type.includes('text/'))            return response.text();
  if (type.includes('image/'))           return response.blob();
  return response.blob(); // safe default for unknown binary
}

Two Kinds of Errors

Robust response handling means treating two very different failure modes correctly:

A comprehensive handler covers both, and enriches the error with detail from the response body when the API provides it:

async function fetchWithErrorHandling(url, options) {
  let response;
  try {
    response = await fetch(url, options);
  } catch (networkError) {
    // Promise rejected -> genuine network/CORS/abort failure
    throw new Error(`Network error: ${networkError.message}`);
  }

  if (!response.ok) {
    // Server answered with 4xx/5xx. Try to pull a message from the body.
    let detail = `${response.status} ${response.statusText}`;
    try {
      const data = await response.json();
      detail = data.message || data.error || detail;
    } catch {
      // body wasn't JSON — keep the status-based message
    }
    const error = new Error(detail);
    error.status = response.status;
    throw error;
  }

  return response.json();
}

Cloning & Streaming

Cloning a response

Because the body is single-use, response.clone() gives you a second readable copy — handy when you want to both use a response and stash it in a cache.

const response = await fetch('/api/data');
const copy = response.clone();

const data = await response.json();   // read the original
await caches.open('v1').then((c) => c.put('/api/data', copy)); // store the copy

Streaming with progress

For large downloads, read the body stream chunk by chunk to report progress — something the one-shot body methods can't do on their own. Combine Content-Length with the stream reader:

async function downloadWithProgress(url, onProgress) {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);

  const total = Number(response.headers.get('Content-Length')) || 0;
  const reader = response.body.getReader();
  const chunks = [];
  let received = 0;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
    received += value.length;
    if (total) onProgress(Math.round((received / total) * 100));
  }

  return new Blob(chunks); // reassemble the downloaded bytes
}

Hands-on Exercise

async function handleResponse(response) {
  if (!response.ok) {
    let message = `${response.status} ${response.statusText}`;
    try {
      const data = await response.json();
      message = data.message || data.error || message;
    } catch {
      // non-JSON error body; keep status message
    }
    const error = new Error(message);
    error.status = response.status;
    throw error;
  }

  if (response.status === 204) return null; // No Content

  const type = response.headers.get('Content-Type') || '';
  if (type.includes('application/json')) return response.json();
  if (type.includes('text/'))            return response.text();
  return response.blob();
}

// Usage
try {
  const post = await handleResponse(
    await fetch('https://jsonplaceholder.typicode.com/posts/1')
  );
  console.log(post.title);
} catch (error) {
  console.error(`Failed (${error.status}):`, error.message);
}

Best Practices

Summary & Quiz

📚 Further Reading

• MDN — Response
• MDN — Headers
• MDN — ReadableStream

🚀 What's Next?

You can now send requests and process what comes back. The next lesson zooms in on error handling strategies — building resilient code with retries, timeouts, and graceful fallbacks for when things go wrong.