Quando sua ferramenta de extração web deve falhar de forma clara em vez de retornar mentiras convincentes

Uma API de extração da web tem uma única função que parece chata até falhar:

retornar os dados que existem ou admitir que não conseguiu obtê-los.

Essa segunda parte é mais importante do que a maioria das pessoas quer admitir.

Quando você coloca um LLM no final de um pipeline de scraping, você obtém um modo de falha desagradável. A busca falha, a página é bloqueada, o texto do PDF está vazio ou o site retorna uma página CAPTCHA, e o modelo ainda tenta ser útil. Útil, neste caso, significa inventar um JSON plausível.

Isso é pior do que um 500.

Um 500 diz ao seu pipeline para tentar novamente, redirecionar, alertar ou pular. JSON fabricado envenena silenciosamente o que vem a seguir.

O padrão que acabamos usando

Para a API Haunt, o caminho de extração é deliberadamente chato antes de ser inteligente:

1. buscar a página diretamente
2. recorrer a caminhos de busca/renderização mais fortes quando necessário
3. inspecionar o que realmente veio de volta
4. só pedir ao modelo para extrair quando há conteúdo real na página
5. retornar uma falha estruturada quando a página é inacessível ou claramente uma parede de verificação

A parte chave é o passo 3. Não trate "HTTP 200" como "conseguimos a página". Muitos sites retornam um código de status bem-sucedido para:

• paredes de login
• paredes de consentimento
• páginas CAPTCHA
• shells JavaScript sem conteúdo significativo
• envoltórios PDF com texto vazio
• páginas de soft-block que parecem HTML normal para um parser ingênuo

Se você passar isso diretamente para um LLM e pedir nomes de produtos, preços, detalhes da empresa ou qualquer outra coisa, você está convidando a ficção.

Como é uma boa falha

Uma boa falha de extração deve ser chata e legível por máquina:

{
  "success": false,
  "error_type": "captcha_required",
  "message": "A página de destino requer verificação humana antes da extração.",
  "url": "https://example.com/product"
}

Ou:

{
  "success": false,
  "error_type": "empty_content",
  "message": "A página era acessível, mas nenhum conteúdo extraível foi encontrado.",
  "url": "https://example.com/report.pdf"
}

Isso dá ao chamador algo útil:

• tentar novamente mais tarde
• pedir credenciais
• usar uma fonte diferente
• marcar o registro como não resolvido
• escalar para um humano

O que não deve fazer é retornar:

{
  "company_name": "Example Holdings Ltd",
  "revenue": "$12.4M",
  "employees": 87
}

quando nada disso apareceu na página.

Uma pequena planilha assombrada, agora com alucinações de qualidade de investidor. Maravilhoso.

Guardrails simples que você pode adicionar

Se você está construindo isso você mesmo, adicione verificações antes da extração:

def has_meaningful_content(text: str) -> bool:
    if not text or len(text.strip()) < 200:
        return False

    bad_markers = [
        "verifique se você é humano",
        "verificando seu navegador",
        "captcha",
        "ative o javascript",
        "acesso negado",
        "login necessário",
    ]

    lowered = text.lower()
    return not any(marker in lowered for marker in bad_markers)

Isso não é suficiente por si só, mas captura uma quantidade surpreendente de lixo antes que o modelo tenha a chance de decorá-lo.

Além disso, faça o modelo responder com base em evidências, não em intuições:

Extraia apenas os campos que estão explicitamente presentes no conteúdo da página fornecida.
Se um campo estiver ausente, retorne nulo.
Se o conteúdo não for a página solicitada, retorne um objeto de erro de extração.
Não inferir, adivinhar ou preencher lacunas com conhecimento geral.

Então valide a saída. Se todos os campos estiverem misteriosamente perfeitos após uma busca fraca, desconfie. A máquina está sorrindo demais.

Onde o MCP torna isso mais afiado

Fluxos de trabalho de agentes tornam esse problema pior porque a saída nem sempre vai direto para um humano. Claude, Cursor ou outro agente pode chamar uma ferramenta, receber JSON e continuar planejando a partir disso.

Uma má extração se torna um raciocínio ruim.

Então, para as ferramentas MCP, eu acho que o contrato...