Skip to content
ENPT

Código de status HTTP · Erros do cliente (4xx)

Erro 426 Upgrade Required

O erro 426 Upgrade Required significa que o servidor se recusa a atender no protocolo atual, mas atende se o cliente trocar para o protocolo indicado no cabeçalho Upgrade. A causa mais comum é abrir uma URL de WebSocket com um pedido HTTP normal, ou um proxy que descarta os cabeçalhos de Upgrade.

Dados sobre este código de status
Classe4xx, Erros do cliente
Definido emRFC 9110 §15.5.22
Pode ir para o cache por padrãoSó com Cache-Control ou Expires explícitos
Pode repetir o pedidoSim, usando o protocolo indicado no cabeçalho Upgrade
Cabeçalhos relevantes
  • Upgrade: obrigatório no 426; indica o protocolo que o servidor quer, como websocket
  • Connection: Connection: Upgrade marca o cabeçalho Upgrade como hop-by-hop

O que significa o 426

A RFC 9110, seção 15.5.22, exige que a resposta 426 traga um cabeçalho Upgrade com os protocolos aceitos, e o exemplo da própria RFC pede HTTP/3.0. No tráfego real o protocolo é quase sempre websocket: a biblioteca ws do Node.js, por exemplo, responde 426 a um pedido HTTP comum feito ao servidor dela.

Uma conexão WebSocket começa como um GET em HTTP/1.1 com Upgrade: websocket e Connection: Upgrade. Se você cola o endpoint numa aba do navegador, ou um proxy reverso repassa o pedido sem esses dois cabeçalhos, o servidor vê HTTP comum e responde 426.

Causas comuns

Se você está visitando o site

  • Você abriu um endereço de WebSocket (algo como /ws ou /socket) direto na barra de endereços do navegador.
  • Um proxy corporativo ou antivírus remove o cabeçalho Upgrade dos pedidos que saem.

Se você administra o servidor

  • O nginx na frente da aplicação repassa /ws sem proxy_http_version 1.1 e sem os cabeçalhos Upgrade e Connection, então o backend nunca vê o handshake.
  • Um load balancer ou plataforma com suporte a WebSocket desligado para aquela rota.
  • Um health check ou sonda de monitoramento mandando GET simples para a porta do WebSocket.

Como resolver

Se você está visitando o site

  • Abra a página que usa o socket, não a URL do socket; a página abre a conexão para você.
  • Se o app só falha numa rede específica, tente outra rede ou desative o proxy que filtra o tráfego.

Se você administra o servidor

  • No nginx, adicione proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; na location do WebSocket.
  • Aponte os health checks para uma rota HTTP normal, não para o endpoint do socket.
  • Teste o handshake direto: curl -i -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" https://exemplo.com/ws deve devolver 101.

Como enviar um 426

Express (Node.js)
app.get('/ws', (req, res) => {
  res.set('Upgrade', 'websocket');
  res.set('Connection', 'Upgrade');
  res.status(426).json({ error: 'This endpoint only accepts WebSocket connections' });
});
Next.js App Router (route handler)
// app/ws/route.ts
export async function GET() {
  return Response.json(
    { error: 'This endpoint only accepts WebSocket connections' },
    { status: 426, headers: { 'Upgrade': 'websocket', 'Connection': 'Upgrade' } }
  );
}
Go net/http
mux.HandleFunc("GET /ws", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Upgrade", "websocket")
	w.Header().Set("Connection", "Upgrade")
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusUpgradeRequired) // 426
	w.Write([]byte(`{"error":"This endpoint only accepts WebSocket connections"}`))
})
Python FastAPI
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/ws")
def websocket_only():
    raise HTTPException(status_code=426, detail="This endpoint only accepts WebSocket connections", headers={"Upgrade": "websocket", "Connection": "Upgrade"})
Nginx
location /ws {
  if ($http_upgrade !~* ^websocket$) {
    add_header Upgrade websocket always;
    return 426;
  }
  proxy_pass http://app;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}

Costuma ser confundido com

426 vs 101
O 101 Switching Protocols é a resposta de sucesso a um pedido de upgrade; o 426 é a recusa que vem quando você não pediu o upgrade.
426 vs 505
O 505 recusa a versão do HTTP na linha do pedido; o 426 aceita o pedido mas quer outro protocolo, indicado no Upgrade.

Perguntas frequentes

Por que recebo 426 Upgrade Required de um servidor WebSocket?
O pedido chegou sem os cabeçalhos Upgrade: websocket e Connection: Upgrade, então pareceu HTTP comum. Ou algo abriu a URL como página, ou um proxy no meio do caminho removeu esses cabeçalhos.
Dá para usar 426 para forçar HTTPS?
A RFC 2817 descreveu o upgrade de HTTP para TLS com Upgrade e 426, mas os navegadores nunca implementaram. Para levar o visitante ao HTTPS, use redirecionamento 301 ou 308 e o cabeçalho HSTS.
Qual cabeçalho a resposta 426 precisa ter?
Upgrade, com o protocolo ou protocolos que o servidor aceita, por exemplo Upgrade: websocket. A RFC 9110 torna esse cabeçalho obrigatório, e ele costuma vir com Connection: Upgrade.

Revisado em por Arielton Oberek.