511

Network Authentication Required

5xx Server Error

Back to list.md

ELI5

You need to log in to the WiFi or network first before you can access any websites.

Server perspective

Use 511 only for captive-portal or network-access control flows where an intercepting proxy requires network authentication before wider access is allowed.

When to use

  • •Return 511 from an intercepting proxy or captive portal, not from a normal origin application
  • •Use it to signal that the client must authenticate to the network before the original request can proceed
  • •WiFi captive portals
  • •Hotel or airport network login
  • •Corporate network authentication
  • •Public network access control

How to respond

  • •Include clear instructions or a link to the captive-portal login flow in the response body
  • •Keep the response distinct from origin authentication so non-browser clients do not mistake it for a normal 401 challenge

Headers to consider

  • •No status-specific authentication challenge header is required; provide navigation to the login or acceptance flow in the response body or portal metadata

Response body

  • •A body is recommended; explain the captive-portal requirement and link to the page where the user can authenticate or accept terms

Server-side pitfalls

  • •Do not use 511 for website or API authentication; use 401 or 403 for origin-application auth flows
  • •Do not let the response look like it came from the target origin server when it is really generated by the network
  • •Website authentication (use 401 Unauthorized)
  • •Proxy authentication (use 407 Proxy Authentication Required)
  • •Application-level auth (use 401 or 403)

Examples

WiFi captive portal

Request:GET https://api.example.test/captive-portal-check
Response:511 Network Authentication Required # Headers Content-Type: text/html; charset=utf-8 # Body <!doctype html> <html><body>Network login required.</body></html>

Must authenticate with WiFi portal before accessing internet

References

Related Status Codes

401

Unauthorized

You need to prove who you are before you can access this. Please log in or provide valid credentials.

407

Proxy Authentication Required

You need to authenticate with the proxy server first before it will forward your request to the destination.