< HTTP/1.1 511 Network Authentication Required

TL;DR: 511 comes from a Wi-Fi gateway or network proxy that wants you to log in before any traffic passes. It is never the website’s response. Apps should treat it as “network not ready”, not retry blindly, and send the user to a browser to authenticate.

What it means

Public Wi-Fi in hotels, airports and cafes intercepts HTTP requests and answers them itself until the user accepts terms. RFC 6585 §6 defines 511 so clients can recognise the interception, instead of getting a 200 with a login page and trying to parse it as the API they asked for. The RFC says the response should include a link to the login page, and must not be sent by origin servers.

HTTP/1.1 511 Network Authentication Required
Content-Type: text/html
Cache-Control: no-store

<html>
  <head>
    <title>Network Authentication Required</title>
    <meta http-equiv="refresh" content="0; url=https://login.hotel-wifi.example/">
  </head>
  <body>
    <p>You need to <a href="https://login.hotel-wifi.example/">authenticate with the local network</a> to gain access.</p>
  </body>
</html>

The redirect is in the body (a meta refresh or a link), not a Location header, so that a client that treats 3xx as “follow transparently” does not leak the original request to the portal.

What actually happens in practice

Many portals do not use 511. They return 302 to a login page, or 200 with HTML, or hijack DNS. That is why your API client may see:

SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

or a TLS certificate error for a HTTPS request that the portal tried to intercept. HTTPS is not interceptable without a certificate warning, so the portal sees the failure and relies on the OS to open a login sheet via its own detection probe.

Operating systems detect portals by fetching a URL with a known answer:

curl -i http://connectivitycheck.gstatic.com/generate_204
# open network: HTTP/1.1 204 No Content
# captive:      200 / 302 / 511 with a portal page instead

Handling it in an app

• Treat 511 as “network requires sign-in”. Show a message and a button to open the browser. Do not display the portal HTML, and never send credentials to the host that returned it.
• Do not retry in a tight loop and do not mark the endpoint as down in your own monitoring: it is the user’s network.
• If a response that should be JSON is HTML, or the host you reached presented an unexpected certificate, suspect a captive portal before suspecting your backend.
• Do not cache: Cache-Control: no-store on 511 bodies prevents the login page being stored as your resource.
• If you run a captive portal gateway, return 511 for non-browser HTTP requests (those without Accept: text/html) and keep HTTP/HTTPS interception to the minimum the OS probes require. RFC 8910 offers a cleaner approach: advertise the portal URL through DHCP or router advertisements so clients do not rely on interception.

Related

• 407 Proxy Authentication Required: a proxy wants credentials, you know about it.
• 401 Unauthorized
• 403 Forbidden
• 502 Bad Gateway