Alt-Svc Header
The Alt-Svc header advertises alternative endpoints for the same origin — such as an HTTP/3 port on a different host — letting clients upgrade transports or migrate mid-connection.
Definition
Alt-Svc (Alternative Services) is a response header that maps an origin to alternates identified by a protocol, host, and port, each with a max-age. Clients cache the mapping, try the alternate for future requests, and fall back to the default endpoint if it fails. It is the standard bootstrap path from HTTP/2 to HTTP/3.
Context and scope
Used to roll out QUIC alongside TCP, to shift traffic to a nearer edge node, and to let long-lived connections survive endpoint changes through connection identifiers.
Common misconceptions
- Alt-Svc forces clients onto the alternate — it is an offer; clients may ignore it and stay on the default path
- Advertising an alternate is enough — the endpoint needs a valid certificate for the origin or upgrade fails
- Alt-Svc is only for HTTP/3 — it can advertise any scheme, port, or host offering the same origin service
Anti-patterns
- Advertising an HTTP/3 alternate whose UDP path is blocked for a subset of users without fallback telemetry
- Setting a long max-age on an alternate that is later decommissioned, straining clients on cached mappings
- Pointing alternates at hosts whose certificates do not cover the origin, breaking every upgrade attempt
Related concepts
Related examples
Authoritative source
What it is
Alt-Svc decouples the origin identity from the serving endpoint. A response from example.com can say that the same service is also available as h3 on alt.example.com port 443 for one day. The client caches this and probes the alternate on subsequent requests, racing or preferring it per its own policy.
How it works
The header lists services with protocol identifiers, authority, and max-age; the ma parameter controls caching and requires clear reporting of failures. Certificate validation for the alternate uses the original origin name, so SAN or wildcard coverage is required. The alt-svc-svc draft extends mapping to QUIC transport parameters.
When to use it
Protocol upgrades to HTTP/3, moving traffic to anycast or regional edges, and draining endpoints during maintenance all use Alt-Svc as the reassignment mechanism. QUIC connection IDs make mid-flight migration seamless when the alternate shares state.
Pitfalls
A stale advertisement after a service decommission causes repeated failed probes; keep max-age modest during change windows. Some clients require successful alternate requests before fully switching, so early metrics look mixed. Monitor protocol distribution and fallback rates, not just availability.