HTTP 414 URI Longa Demais: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um navegador, cliente de API, crawler, ferramenta de monitoramento ou verificador recebe uma resposta HTTP 414 URI Too Long.
• O endereço com falha contém um path, uma query string, parâmetros repetidos ou dados fortemente codificados incomumente longos.
• O problema pode afetar um link, uma rota, uma cadeia de redirecionamentos ou um tipo de solicitação, enquanto URLs mais curtas continuam funcionando.
• Um redirecionamento pode deixar a URL mais longa a cada salto, até que um intermediário ou a origem a rejeite.
• Os cabeçalhos de resposta podem identificar um servidor web, proxy reverso, CDN, WAF ou camada de cache, em vez da própria aplicação.
• A resolução de DNS e a negociação de TLS podem ser concluídas porque a solicitação chegou a um endpoint que fala HTTP.

Causas principais, por probabilidade

Causas mais prováveis

1. Uma query string grande demais. Um parâmetro de pesquisa, filtro, rastreamento, paginação ou estado pode serializar mais dados do que o endpoint aceita.
2. Um erro na geração da URL. O código do lado do cliente ou do servidor pode anexar o mesmo parâmetro repetidamente, duplicar uma URL codificada ou colocar na URI dados que não deveriam estar ali.
3. Uma cadeia de redirecionamentos crescente. O destino de um redirecionamento pode adicionar repetidamente URLs de retorno, parâmetros de rastreamento ou cópias codificadas do endereço original.
4. Um limite no proxy, CDN, WAF ou servidor web. A solicitação pode ser rejeitada antes de chegar à aplicação, e diferentes camadas podem ter limites de URI diferentes.
5. Construção inesperada da solicitação. Codificação incorreta, uma URL absoluta inserida acidentalmente em outro parâmetro ou uma integração malformada podem produzir um destino de solicitação incomumente longo.
6. Validação intencional da solicitação ou proteção contra abuso. Um componente pode rejeitar destinos de solicitação excepcionalmente grandes para reduzir o consumo de recursos ou bloquear tráfego suspeito.

Como corrigir

Para visitantes e usuários de API

1. Verifique o endereço exato. Procure parâmetros de query repetidos, uma URL copiada que contenha dados de rastreamento, um redirecionamento incompleto ou um valor codificado inesperadamente longo.
2. Abra a rota base sem parâmetros opcionais quando for seguro fazer isso. Se o endereço mais curto funcionar, adicione os filtros ou parâmetros novamente em pequenos grupos para encontrar o causador.
3. Evite atualizar a página repetidamente. Tentar novamente não encurta uma URI longa demais e pode aumentar a carga se houver um redirecionamento ou loop no cliente.
4. Use o formato de solicitação documentado. Se uma API aceitar o envio de um filtro ou payload grande no corpo da solicitação, use esse método somente conforme documentado; não altere uma solicitação de GET para POST apenas para contornar um erro.
5. Entre em contato com o proprietário do site ou da API informando a URL ou o padrão de solicitação sanitizado, o horário, os detalhes do cliente e a resposta 414. Remova cookies, cabeçalhos de autorização, chaves de API e outros segredos.

Para desenvolvedores

1. Capture a solicitação com precisão. Registre o método HTTP, host, tamanho do path e da query string, histórico de redirecionamentos, status final e cabeçalhos de resposta relevantes. Oculte credenciais e dados pessoais.
2. Reproduza com a menor solicitação que falha. Remova os parâmetros opcionais um por vez ou reduza seus valores até que a resposta mude. Isso diferencia um problema de tamanho da URI de erros de roteamento ou autenticação.
3. Inspecione a construção da URL. Verifique filtros de pesquisa, paginação, parâmetros de rastreamento, URLs de retorno, codificação aninhada e loops que anexem repetidamente a URL atual.
4. Revise os redirecionamentos. Compare cada valor de Location na cadeia e confirme que ele não continua adicionando a URL anterior nem duplicando parâmetros.
5. Escolha o transporte correto para os dados. Mantenha na URI os identificadores necessários para uma recuperação segura e armazenável em cache do recurso, mas use o formato de corpo de solicitação compatível com a aplicação para entradas maiores quando a semântica e o modelo de segurança permitirem.
6. Verifique a camada geradora. Compare o horário e os detalhes da solicitação com os logs da aplicação, do servidor web, do proxy reverso, da CDN e do WAF. O primeiro componente que registra a rejeição geralmente é a camada a ser investigada.
7. Aplique a correção mais específica possível. Corrija a geração da URL, a lógica de redirecionamento ou o tratamento de parâmetros antes de alterar um limite do servidor ou intermediário. Se um limite precisar ser alterado, obtenha autorização, avalie as implicações de recursos e segurança, atualize a camada correta e teste rotas representativas.
8. Teste novamente a solicitação original e casos próximos. Confirme que a solicitação pretendida funciona, que solicitações malformadas ou excessivas continuam sob controle, que os redirecionamentos terminam e que as rotas não relacionadas mantêm seus códigos de status esperados.

Prevenção e como verificar a correção

• Defina limites para a quantidade de parâmetros de query e o tamanho dos valores na validação da aplicação.
• Impeça que o código de redirecionamento aninhe ou codifique novamente a URL atual repetidamente.
• Teste filtros longos, paginação, parâmetros de rastreamento e cadeias de redirecionamento nos testes de integração.
• Mantenha documentadas e, quando houver suporte, sob controle de versão as configurações do proxy, CDN, WAF, servidor web e aplicação.
• Monitore respostas 414 por rota, cliente e implantação para que uma regressão na geração de URLs seja identificada.
• Prefira corpos de solicitação compatíveis para entradas grandes da aplicação, em vez de codificar grandes volumes de dados em uma URL.
• Evite colocar credenciais ou dados confidenciais em URLs, pois eles podem aparecer no histórico, nos logs ou nos dados de referência.

Perguntas frequentes