X-Response-Time

TL;DR: Non-standard header showing server processing time in milliseconds. Useful for performance monitoring, but consider using the standardized Server-Timing header instead.

What is X-Response-Time?

The X-Response-Time header is a non-standard response header that reports how long the server took to handle a request.

It is common in Express/Koa stacks and API gateways for quick latency debugging.

Example Response

X-Response-Time: 142ms
```javascript

## What It Usually Measures

Most implementations measure time spent inside your app process:

- Routing and middleware
- Database/cache calls
- Serialization and rendering

It usually does **not** include full client round-trip time, DNS resolution, or browser rendering.

## Correct Express Implementation

Avoid setting headers after `finish` because headers are already sent by then. Use middleware that computes timing before headers are written:

```javascript
import express from 'express'
import responseTime from 'response-time'

const app = express()
app.use(responseTime())

If you need a custom format:

app.use(
  responseTime((req, res, time) => {
    res.setHeader('X-Response-Time', `${time.toFixed(1)}ms`)
  })
)
```text

## When to Expose It

Safe default approaches:

- Expose in staging/internal environments
- Keep production exposure for authenticated observability endpoints
- Avoid leaking detailed timings on sensitive auth flows

## Recommended Standard Alternative

Use [Server-Timing](/headers/server-timing) for standardized performance metrics.

```http
Server-Timing: app;dur=142

You can publish both during migration:

X-Response-Time: 142ms
Server-Timing: app;dur=142

Measuring and Exposing Response Time Correctly

The most common implementation mistake with X-Response-Time is setting the header after the response has already been sent. In Node.js, response headers must be written before the body. If you try to set a header in a finish event listener, it will silently fail because the headers were already flushed.

The correct pattern is to record the start time at the beginning of the request, then set the header in middleware that wraps the response before it is sent. The response-time npm package does this correctly by monkey-patching res.end() to inject the header just before the response is finalized.

What X-Response-Time measures matters for interpretation. Most implementations measure the time from when the Node.js process received the request to when it started writing the response. This excludes network transit time, TLS handshake overhead, and the time for the response body to reach the client. It is a measure of application processing time, not end-to-end latency.

For production observability, X-Response-Time is useful as a quick sanity check in browser DevTools, but it should not replace proper APM instrumentation. Tools like Datadog, New Relic, or OpenTelemetry capture the same timing data with better context, correlation IDs, and alerting capabilities. The standardized Server-Timing header is the recommended replacement for X-Response-Time in new applications, as it integrates directly with browser DevTools performance panels and the JavaScript Performance API.