Alt-Svc

What is the Alt-Svc header?

The Alt-Svc response header, defined in RFC 7838 (HTTP Alternative Services), tells the client that the same origin is also available somewhere else: over a different protocol, on a different port, or on a different host. Its most common use by far is advertising HTTP/3: a server answering over HTTP/1.1 or HTTP/2 sends Alt-Svc: h3=":443", and a client that speaks HTTP/3 can switch to QUIC for later requests.

The value is either the keyword clear or a comma-separated list of alternatives in the server’s order of preference. Each alternative is an ALPN protocol ID and an authority (an optional host, then a colon and a port), followed by optional parameters:

clear tells the client to forget every alternative it has cached for that origin. A new Alt-Svc value replaces the cached set rather than adding to it.

A client using an alternative should send the Alt-Used request header naming the host and port it actually connected to. In HTTP/2, a server can send the same information in an ALTSVC frame instead of the header.

API Usage & Best Practices

• It is a hint, never a redirect. The origin does not change: the URL, the Host, cookies and same-origin rules all stay the same. The client may ignore the advertisement entirely, and many server-side HTTP clients do. Never depend on clients switching.
• Let your edge send it. If your CDN or load balancer terminates HTTP/3, it usually adds Alt-Svc for you. Emitting it from the application as well risks advertising a protocol on a port where nothing listens. Advertise only what the edge actually serves.
• The alternative must be authenticated for the origin. RFC 7838 requires the client to validate the alternative’s certificate against the origin’s host name, and to send SNI for the origin. An alternative on another host only works if that host presents a certificate valid for your API’s name. Cleartext alternatives such as h2c cannot be used this way.
• Use a sensible ma. The 24-hour default is fine for a stable deployment. Before you remove an alternative, lower ma well ahead of time, or send clear, so clients are not left trying a port that is gone. A client falls back to the origin if the alternative fails, but every failed attempt costs it time.
• Answer misrouted requests with 421. If a request reaches an alternative that cannot serve that origin, return 421 Misdirected Request. RFC 7838 says the client must then remove that alternative from its cache, and it may retry the request on another connection.
• Expect DNS to take over discovery. HTTPS DNS records (RFC 9460) can advertise HTTP/3 before the first connection, which Alt-Svc cannot. Many deployments send both. Alt-Svc remains the fallback when the DNS record is absent or the resolver does not return it.
• Do not use it for load balancing or failover. Clients choose whether and when to use an alternative, and cache it for ma seconds. That is too loose and too sticky to steer traffic reliably.

Examples

Advertising HTTP/3 on the same host and port, remembered for a day:

HTTP/2 200
Content-Type: application/json
Alt-Svc: h3=":443"; ma=86400

HTTP/3 on a different port, with HTTP/2 on another host as a second choice:

HTTP/1.1 200 OK
Alt-Svc: h3=":8443"; ma=3600, h2="alt.example.com:443"; ma=3600

A later request sent over the HTTP/2 alternative on alt.example.com. The authority is still the origin:

GET /v1/orders HTTP/2
Host: api.example.com
Alt-Used: alt.example.com

Telling clients to forget all alternatives before decommissioning them:

HTTP/1.1 200 OK
Alt-Svc: clear