Códigos de status HTTP no web scraping: 403, 407, 429, 503

As linhas mais comuns no log de um scraper não são as respostas 200 de sucesso, e sim os códigos 403, 429 e 503 que aparecem no meio delas. Cada um desses códigos descreve um problema diferente e pede uma reação diferente. Um script que trata todos igual, "tentar de novo três vezes", ou insiste contra um bloqueio permanente e piora a situação, ou perde dados em um problema temporário que teria passado em poucos segundos.

Neste artigo, explicamos como ler os códigos de status HTTP, o que significam os códigos mais encontrados no scraping (403, 407, 429 e 503) e as causas prováveis por trás deles. Depois, vemos 502, 504 e os erros de conexão, como usar o cabeçalho Retry-After, e reunimos em uma única tabela quais códigos tentar de novo e em quais parar. No final há um exemplo em Python testado que aplica essas decisões.

Como ler os códigos de status HTTP?#

Toda resposta HTTP começa com um código de status de três dígitos. O primeiro dígito define a classe da resposta. Os códigos são definidos na seção 15 da RFC 9110; a lista de códigos de status do MDN também traz explicações curtas e exemplos de cada um.

A distinção mais importante para o scraping é esta: a maioria dos códigos 4xx dá o mesmo resultado quando você envia exatamente a mesma requisição de novo. É preciso mudar algo na requisição. A maioria dos códigos 5xx é temporária, e a mesma requisição pode dar certo depois de esperar um pouco. O 429 é a exceção: é um código 4xx, mas se resolve com espera.

Mais um aviso que vale para qualquer código: ver 200 não significa que você obteve os dados que queria. Sistemas de proteção de bots muitas vezes devolvem uma página de verificação com código 200. Antes de considerar uma resposta como sucesso, confira se a página contém um elemento esperado (um título de produto, um campo de preço).

O que significa 403 Forbidden?#

O 403 diz que o servidor entendeu a sua requisição, mas se recusa a atendê-la. Segundo a RFC 9110, o servidor não é obrigado a explicar o motivo. A diferença em relação ao 401 Unauthorized, usado quando falta autenticação, é que no 403 adicionar credenciais geralmente não muda o resultado.

Causas prováveis de um 403 no scraping:

• Reputação ou tipo de IP. Sites que restringem tráfego de endereços de data center devolvem 403 diretamente a esses endereços.
• Restrição geográfica. O site só permite acesso de determinados países.
• Cabeçalhos ausentes ou incoerentes. O valor padrão de User-Agent da biblioteca ou uma combinação de cabeçalhos que nenhum navegador envia.
• Uma regra de firewall de aplicações web (WAF). A requisição correspondeu a uma regra de segurança.
• Bloqueio por causa do seu tráfego anterior. Um endereço IP que ultrapassa o limite de taxa por muito tempo pode, depois de um tempo, começar a receber 403 em vez de 429.
• Uma página que realmente exige autorização. Um caminho que não pode ser acessado sem login.

O que fazer: não envie a mesma requisição de novo na hora. Tente abrir o endereço em um navegador real com o mesmo IP. Se abrir no navegador, o problema está na sua própria requisição (cabeçalhos, velocidade); se não abrir, o problema é o IP ou a localização. Explicamos em detalhe as causas dos bloqueios e as soluções legítimas em Como fazer web scraping sem ser bloqueado.

O que significa 407 Proxy Authentication Required?#

O 407 não vem do site de destino, e sim do servidor proxy. Ele significa que o proxy quer que você comprove a sua identidade antes de encaminhar a requisição ao destino. Então, quando vir 407, você precisa olhar a sua conexão com o proxy, não as regras do site de destino.

Causas prováveis:

• O usuário ou a senha estão errados.
• A senha tem caracteres especiais como @, : ou / sem codificação dentro do endereço do proxy (@ → %40).
• O método de whitelist de IP está em uso, mas o endereço IP de onde vem a conexão não está na lista.
• A biblioteca não envia ao proxy as credenciais que estão no endereço.
• O saldo ou a franquia de tráfego da conta acabou.

As bibliotecas mostram o 407 de formas diferentes. Em requisições HTTPS, o túnel do proxy não chega a ser aberto, então muitas vezes você recebe uma exceção em vez de um objeto de resposta: o Python Requests lança ProxyError, e o HTTPX também lança ProxyError; no Node.js, o Axios devolve um erro com código de status 407. Mostramos as diferenças entre bibliotecas com exemplos testados em Como usar proxy no Node.js.

O que fazer: não tente de novo; corrija a configuração. Confira na saída do curl -v se o cabeçalho Proxy-Authorization está sendo enviado; o comando está em Como usar proxy com cURL. Percorremos passo a passo os dois métodos de autenticação e o diagnóstico do 407 em Autenticação de proxy: user:pass ou whitelist de IP.

O que significa 429 Too Many Requests?#

O 429 diz que você enviou requisições demais em um determinado período. O código é definido na seção 4 da RFC 6585, que afirma que o servidor pode enviar junto com a resposta um cabeçalho Retry-After dizendo quanto tempo esperar.

Sobre o que o limite de taxa é contado varia conforme o site:

• Por endereço IP: as requisições do mesmo endereço são somadas.
• Por sessão ou cookie: as requisições da mesma sessão são somadas; trocar de IP não zera o contador.
• Por chave de API: em APIs oficiais, o limite geralmente fica ligado à chave.
• Por endpoint: em endpoints pesados, como páginas de busca, o limite é menor do que em páginas de produto.

Algumas APIs informam a sua franquia restante com cabeçalhos como X-RateLimit-Remaining e X-RateLimit-Reset. Esses nomes de cabeçalho não são padronizados e variam de serviço para serviço; consulte a documentação da API que você usa.

O que fazer: se houver Retry-After, espere esse tempo. Se não houver, aplique backoff exponencial: 1 segundo na primeira tentativa, depois 2, 4, 8 segundos, adicionando um componente aleatório a cada espera. Ao mesmo tempo, reduza a concorrência; se você espera e continua na mesma velocidade, logo recebe 429 de novo.

O que significa 503 Service Unavailable?#

O 503 diz que o servidor não consegue atender a requisição agora, mas que a situação é temporária. Manutenção, sobrecarga ou um servidor de aplicação caído por trás são causas típicas. Segundo a RFC 9110, o servidor pode informar com Retry-After quando tentar de novo.

No scraping, o 503 tem duas faces diferentes:

• Carga real ou manutenção. O site devolve 503 para todo mundo. Não há o que fazer além de esperar.
• Um bloqueio temporário da proteção de bots. Alguns sistemas de proteção devolvem 503 com uma página de verificação ao tráfego que consideram suspeito. Se o corpo tiver uma tela de verificação, o problema não é a carga do servidor, e sim o seu próprio tráfego.

O que fazer: diferencie os dois casos olhando o corpo. Se for carga real, espere com Retry-After ou backoff exponencial. Se aparecer uma página de verificação, revise a sua velocidade e a sua identidade de cliente em vez de tentar de novo. Explicamos por que essas telas aparecem na automação de navegador em Puppeteer e CAPTCHA.

502, 504 e erros de conexão#

Um scraper que usa proxy esbarra, além das respostas do site de destino, em erros do próprio proxy. Esses códigos importam para descobrir em qual elo da cadeia está o problema.

• 500 Internal Server Error: ocorreu um erro na aplicação de destino. Às vezes é específico de uma página. Pode ser tentado de novo uma ou duas vezes; se continuar, pule esse endereço.
• 502 Bad Gateway: um gateway intermediário (proxy, CDN ou reverse proxy) não conseguiu obter uma resposta válida do servidor por trás. No contexto de proxy, pode significar que o proxy não conseguiu chegar ao destino. Tente de novo depois de uma espera curta.
• 504 Gateway Timeout: o gateway não recebeu a resposta do servidor por trás a tempo. Aparece quando o destino está lento ou o ponto de saída do proxy está longe. Tente de novo.
• 408 Request Timeout: o servidor esgotou o tempo esperando a requisição ser concluída. Tente de novo.
• Erros de conexão: não há código; o cliente lança uma exceção. Conexão recusada (ECONNREFUSED), conexão redefinida (ECONNRESET), timeout, host não encontrado (ENOTFOUND) e assim por diante. Se o endereço ou a porta estiverem errados, nenhuma nova tentativa resolve; em situações temporárias, como uma queda de rede, tentar de novo ajuda.
• Códigos próprios de CDN: algumas CDNs usam códigos não padronizados na faixa 520-526. Eles geralmente descrevem problemas de conexão entre a CDN e o servidor do próprio site.

404 Not Found e 410 Gone dizem que a página não existe. Em vez de tentar de novo, tire o endereço da sua lista; se de repente aparecerem muitos 404, a estrutura de URLs do site pode ter mudado.

Como usar o Retry-After?#

O cabeçalho Retry-After pode chegar em duas formas:

• Um número de segundos: Retry-After: 120 → espere 120 segundos.
• Uma data HTTP: Retry-After: Wed, 16 Sep 2026 07:28:00 GMT → tente depois dessa data.

Quatro regras para usá-lo corretamente:

1. Se o cabeçalho existir, não chute; siga-o. O tempo que o servidor informa é mais preciso do que qualquer backoff que você calcular.
2. Defina um limite superior. Se o cabeçalho indicar algo longo, como várias horas, deixe o endereço para uma execução posterior em vez de travar o seu script por todo esse tempo.
3. Aplique a espera ao site, não só àquela requisição. Se você segura a requisição que recebeu 429, mas continua enviando em paralelo outras requisições ao mesmo site, o limite continua sendo ultrapassado.
4. Interprete também a forma de data. Um código que só espera um número ignora um cabeçalho que chega como data. Compartilhamos uma função Python que trata as duas formas em Como fazer web scraping sem ser bloqueado.

Quais códigos tentar de novo e em quais parar?#

Exemplo: novas tentativas que decidem pelo código de status#

O exemplo abaixo usa o cliente assíncrono do HTTPX. Nos códigos 408, 429 e 5xx, ele respeita o cabeçalho Retry-After; se não houver cabeçalho, aplica backoff exponencial com um componente aleatório. Nos códigos em que tentar de novo não muda o resultado, como 403, 404 e 407, ele para lançando uma exceção separada. Os erros de autenticação do proxy (que chegam como ProxyError em requisições HTTPS) também entram nesse grupo.

import asyncio
import random

import httpx

RETRY_STATUS = {408, 429, 500, 502, 503, 504}
STOP_STATUS = {400, 401, 403, 404, 407, 410}


class StopScraping(Exception):
    """Casos em que tentar de novo não muda o resultado."""


def backoff(response, attempt, base=1.0, cap=60.0):
    retry_after = response.headers.get("Retry-After") if response is not None else None
    if retry_after and retry_after.isdigit():
        return min(int(retry_after), cap)
    return min(cap, base * 2**attempt) * random.uniform(0.5, 1.0)


async def fetch(client, url, attempts=5):
    for attempt in range(attempts):
        response = None
        try:
            response = await client.get(url)
        except httpx.ProxyError as exc:
            raise StopScraping(f"Erro de proxy (confira as credenciais): {exc}") from exc
        except httpx.TransportError:
            pass  # conexão caída, timeout: pode tentar de novo
        else:
            status = response.status_code
            if status < 400:
                return response
            if status in STOP_STATUS:
                raise StopScraping(f"{url}: HTTP {status}, não vai tentar de novo")
            if status not in RETRY_STATUS:
                return response
        await asyncio.sleep(backoff(response, attempt))
    raise RuntimeError(f"{url}: sem resultado após {attempts} tentativas")


async def main():
    proxy = "http://user:pass@pr.proxynet.io:8000"
    async with httpx.AsyncClient(proxy=proxy, timeout=20, follow_redirects=True) as client:
        urls = ["https://example.com/product/1", "https://example.com/product/2"]
        results = await asyncio.gather(*(fetch(client, u) for u in urls), return_exceptions=True)
        for url, result in zip(urls, results):
            print(url, result if isinstance(result, Exception) else result.status_code)


asyncio.run(main())

Amplie o exemplo em dois pontos para o seu próprio trabalho. Primeiro, o asyncio.gather inicia todos os endereços de uma vez; em um trabalho real, limite com asyncio.Semaphore o número de requisições simultâneas ao mesmo site. Segundo, o Retry-After também pode chegar como data HTTP; se precisar interpretar essa forma, use a função indicada acima. As diferenças entre o HTTPX e outras bibliotecas Python estão em HTTPX, Requests ou AIOHTTP.

Registrar e monitorar erros#

Use os códigos de status não só para decidir na hora, mas também para acompanhar a saúde do trabalho. Registrar estes números a cada execução ajuda a perceber problemas cedo:

• Respostas por código: se a taxa de 429 sobe, você está rápido demais; se a de 403 sobe, algo mudou do lado do IP ou dos cabeçalhos.
• Distribuição por site e endpoint: o problema está em um site ou em todos? Erros subindo em todos os sites ao mesmo tempo geralmente apontam para o proxy ou para a rede.
• Número de novas tentativas e tempo total de espera: se as novas tentativas ocupam boa parte do tempo do trabalho, a configuração de concorrência está errada.
• Respostas 200 sem o elemento esperado: o único sinal de perda silenciosa de dados.

Casos de uso#

• Monitoramento diário de preços: produtos que retornam 404 saem da lista, e na execução seguinte a concorrência é reduzida nos sites que retornaram 429. A configuração geral está na nossa página de solução de extração de dados.
• Coleta de catálogos de muitos sites: uma taxa de 403 crescente em um site exige diagnóstico separado para esse site; para distribuir a carga, usa-se um Proxies rotativos.
• O seu próprio painel que precisa de sessão: um redirecionamento 302 para a página de login pode mostrar que o IP mudou no meio da sessão; para manter o mesmo IP durante a sessão, prefere-se um Proxies de sessão fixa.
• Uma configuração de proxy nova: se as primeiras requisições retornarem 407 ou ProxyError, o problema não é o destino, e sim as credenciais.

Erros comuns#

• Tentar de novo o mesmo número de vezes em qualquer erro. Repetir 403 e 407 não muda o resultado; só gera tráfego desnecessário.
• Não ler o cabeçalho Retry-After. Voltar antes por conta própria quando o servidor disse quanto esperar.
• Não adicionar componente aleatório ao backoff. Centenas de requisições que falharam no mesmo momento são tentadas de novo no mesmo momento e criam um novo acúmulo.
• Aceitar uma resposta 200 sem olhar o conteúdo. Páginas de verificação geram dados vazios em silêncio.
• Tratar o 407 como erro do site de destino. É preciso conferir a configuração do seu proxy, não o destino.
• Não limitar as novas tentativas. Um loop que continua para sempre diante de um problema permanente desgasta tanto os seus recursos quanto o site de destino.

Guia de decisão#

Perguntas frequentes#

Qual é a diferença entre 403 e 401?#

O 401 Unauthorized diz que a requisição exige autenticação e que você não enviou credenciais válidas. O 403 Forbidden diz que o servidor entendeu a requisição, mas a recusa independentemente das credenciais. No 401, adicionar credenciais pode ser a solução; no 403, geralmente não é.

Por que o erro 407 vem do proxy e não do site de destino?#

Porque a requisição nunca chegou ao destino. O proxy autentica você antes de encaminhar a conexão e, se a autenticação falha, responde ele mesmo. Por isso o 407 não tem nada a ver com as regras do site de destino.

Trocar de IP depois de um 429 é solução?#

Se o limite de taxa é contado por IP, pode ajudar temporariamente, mas não muda a velocidade que causou o problema, e não ajuda em nada se o limite for por sessão ou por conta. A reação certa é esperar e desacelerar; a rotação deve ser planejada desde o início para distribuir a carga.

Quanto esperar se não houver cabeçalho Retry-After?#

Aplique backoff exponencial: comece com alguns segundos, dobre a cada tentativa, defina um limite superior e adicione um componente aleatório a cada espera. Se ainda falhar depois de algumas tentativas, deixe o endereço para uma execução posterior.

Um erro 503 significa que o site caiu?#

Nem sempre. Também pode ser manutenção, carga temporária ou um bloqueio da proteção de bots. Olhe o corpo da resposta: é uma mensagem de manutenção, uma página de erro genérica ou uma tela de verificação?

Recebo erros 502 ao usar proxy. Onde está o problema?#

O 502 diz que o gateway intermediário não conseguiu obter uma resposta válida do servidor por trás. No contexto de proxy, pode significar que o proxy não conseguiu chegar ao destino ou que o destino derrubou a conexão. Teste o mesmo endereço sem proxy: se funcionar sem proxy, o problema está no ponto de saída do proxy; se não funcionar nem sem proxy, o problema está no site de destino.

Em resumo#

Os códigos de status HTTP dizem ao seu scraper o que fazer: 429 e 503 pedem espera, 403 pede diagnóstico, 407 pede correção da configuração do proxy e 404 pede para tirar o endereço. Se houver cabeçalho Retry-After, siga-o; se não houver, use backoff exponencial com componente aleatório e limite todo loop de novas tentativas. Não se esqueça de conferir também o conteúdo das respostas 200. Tipos de proxy adequados ao seu trabalho de coleta de dados estão nos nossos serviços de proxy.