# Documentação do proxy CrawlRelay: guia rápido

> Guia rápido do proxy CrawlRelay: host do gateway e portas, formato de usuário para país, cidade e sessões sticky, erros HTTP e limites. A partir de US$ 0,50/GB, sem KYC.

- URL: https://crawlrelay.com/pt/docs/
- Última atualização: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

Tudo que precisa para enviar a primeira requisição e a referência para consultar depois: parâmetros de segmentação, regras de sessão, códigos de erro e limites.

**Resposta rápida — Como me conecto aos proxies CrawlRelay?**

Aponte qualquer cliente HTTP para `http://USERNAME:PASSWORD@gw.crawlrelay.com:7777` ou SOCKS5 na porta 7778. **CrawlRelay**, um serviço developer-first de proxy residencial, lê segmentação e sessões do usuário: `USERNAME-country-us-city-new_york-session-job1-ttl-30`. Tráfego residencial custa US$ 1,50 por 1 GB e US$ 0,50/GB a partir de 50 GB. Pagar com cripto, sem KYC.

## Configurações de conexão

| Atributo | Valor |
| --- | --- |
| Host do gateway | `gw.crawlrelay.com` |
| Porta HTTP / HTTPS | `7777` (sites HTTPS via `CONNECT`) |
| Porta SOCKS5 | `7778` (use `socks5h://` para resolver DNS na saída) |
| Autenticação | Usuário e senha do seu plano ou de um subusuário, ou uma whitelist de IPs (até 10 IPs) |
| Formato do nome de usuário | `USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}` |
| Duração da sessão | até 30 minutos; o IP pode mudar antes |
| URL para teste | `https://api.ipify.org` retorna o IP de saída em texto simples |
| API de gerenciamento | `https://crawlrelay.com/api/v1`, Chaves API que você pode revogar a qualquer momento ([documentação da API](https://crawlrelay.com/docs/api/)) |

## Como envio minha primeira requisição?

Copie o nome de usuário e a senha do seu painel, e rode um destes. Cada um imprime o endereço IP que o site vê, que geralmente muda a cada execução.

*curl*

```bash
curl -x http://USERNAME-country-us:PASSWORD@gw.crawlrelay.com:7777 https://api.ipify.org
```

*Python (requests)*

```python
import requests

proxy = "http://USERNAME-country-us:PASSWORD@gw.crawlrelay.com:7777"
r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=(10, 30))
print(r.text)
```

*Node.js 22+ (undici)*

```javascript
import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent("http://USERNAME-country-us:PASSWORD@gw.crawlrelay.com:7777");
const res = await fetch("https://api.ipify.org", { dispatcher });
console.log(await res.text());
```

## Como construir o nome de usuário?

Comece com o nome de usuário do seu painel e adicione parâmetros com hífens, na ordem do formato acima. Cada parâmetro é opcional. Os valores devem estar em minúsculas, e nomes de cidade usam underscores (`new_york`, `sao_paulo`). A disponibilidade das cidades varia.

| Meta | Nome de usuário |
| --- | --- |
| Qualquer país, rotacionando a cada conexão | `USERNAME` |
| Alemanha | `USERNAME-country-de` |
| Paris | `USERNAME-country-fr-city-paris` |
| Texas | `USERNAME-country-us-state-tx` |
| Um código postal | `USERNAME-country-us-zip-10001` |
| Um provedor de internet | `USERNAME-country-us-asn-7922` |
| Mesma IP por até 30 minutos | `USERNAME-country-gb-session-abc123-ttl-30` |

Se sua senha contém `@`, `:` ou `/`, codifique no formato URL antes de colocar em uma URL de proxy. A [página do erro 407](https://crawlrelay.com/pt/docs/errors/407-proxy-authentication-required/) mostra como.

## Como funcionam sessões rotativas e sticky?

Um nome de usuário **sem** `session-` recebe um IP do pool a cada nova conexão TCP, geralmente um diferente. Um nome de usuário **com** `session-<id>-ttl-<minutes>` mantém o mesmo IP de saída para essa sessão até o TTL acabar ou o dispositivo residencial ficar offline.

- A rotação ocorre por conexão, não por requisição: keep-alive reutiliza o mesmo IP de saída.
- Use um ID de sessão novo por tarefa, contexto do navegador ou fluxo de conta.
- Dois scrapers que enviam o mesmo ID de sessão compartilham um IP de saída.

O [guia de sessões](https://crawlrelay.com/pt/docs/sessions/) explica a reutilização de conexões em cada biblioteca.

## Quais erros verei e quem os envia?

Primeiro descubra quem respondeu: o gateway ou o site atrás dele.

| Você vê | Enviado por | Causa usual | O que fazer |
| --- | --- | --- | --- |
| [407](https://crawlrelay.com/pt/docs/errors/407-proxy-authentication-required/) | Gateway | Credenciais erradas ou não codificadas | Corrija o nome de usuário ou senha; nunca tente novamente sem analisar |
| [ERR_TUNNEL_CONNECTION_FAILED](https://crawlrelay.com/pt/docs/errors/err-tunnel-connection-failed/) | Navegador | CONNECT recusado (geralmente um 407 oculto) | Passe as credenciais como campos, não na URL do servidor |
| [502](https://crawlrelay.com/pt/docs/errors/502-bad-gateway/) / [504](https://crawlrelay.com/pt/docs/errors/504-gateway-timeout/) | Gateway ou CDN | Saída interrompida, destino lento ou fora do ar | Tente novamente em uma nova conexão, com limite |
| [403](https://crawlrelay.com/pt/docs/errors/403-forbidden/) | Site | País errado, cabeçalhos, limite ou recusa | Teste no navegador; diminua a velocidade ou respeite a recusa |
| [429](https://crawlrelay.com/pt/docs/errors/429-too-many-requests/) | Site | Limite de taxa | Respeite o Retry-After; reduza a concorrência por host |
| [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/pt/docs/errors/ssl-wrong-version-number/) | Seu cliente | `https://` antes da URL do proxy | Use `http://` para a URL do proxy |

Todas as entradas de 15 estão na [referência de erros](https://crawlrelay.com/pt/docs/errors/).

## Quais são os limites?

- **Destinos bloqueados:** Sites bancários, governamentais e portais de pagamento, além das portas SMTP (envio de e-mail) 25, 465 e 587. Solicitações para eles são recusadas.
- **Uso:** apenas dados públicos, sob a [Política de Uso Aceitável](https://crawlrelay.com/pt/acceptable-use/). Sem tomada de conta de contas, fraudes, spam ou tentativas de burlar bloqueios deliberados de sites.
- **Tráfego:** cobrado por GB. Uso conta todos os dados enviados e recebidos pelo proxy (upload e download, cabeçalhos incluídos). 1 GB = 1.000.000.000 bytes. Tentativas de conexão que falham antes de alcançar o destino não contam. As solicitações param quando o tráfego do plano acabar.
- **Sessões:** até 30 minutos; o IP pode mudar antes, por exemplo, se o dispositivo residencial sair do ar.
- **Protocolos:** HTTP, HTTPS (CONNECT) e SOCKS5.
- **Concorrência:** não cobrada. Seu limite é o que cada destino aceita; veja o [guia de concorrência](https://crawlrelay.com/pt/docs/concurrency/).

## Como gerencio credenciais e uso?

No painel, ou via REST API em `https://crawlrelay.com/api/v1` com uma chave de API. Chaves API que você pode revogar a qualquer momento. As principais tarefas:

- **Subusuários:** um conjunto de credenciais por scraper ou projeto do cliente, com uma cota opcional de tráfego. Veja a [API de proxy residencial](https://crawlrelay.com/docs/api/residential/).
- **Lista de IPs permitidos:** até 10 IPs que podem conectar sem senha.
- **Uso:** tráfego diário por assinatura, para alertar antes do fim do crawl.
- **Catálogo:** países, cidades, estados e ASNs que você pode segmentar, para que seu código valide um nome de usuário antes de usar.
- **Pedidos:** compre mais tráfego do seu saldo sem abrir o painel. Veja a [API de pedidos](https://crawlrelay.com/docs/api/orders/).

## Guias por biblioteca

- **[Python](https://crawlrelay.com/pt/docs/python/)** — requests, httpx, aiohttp, concorrência assíncrona
- **[Scrapy](https://crawlrelay.com/pt/docs/scrapy/)** — Middleware, sessões por requisição, AutoThrottle
- **[Playwright](https://crawlrelay.com/pt/docs/playwright/)** — Python e Node.js, proxy por contexto
- **[Puppeteer](https://crawlrelay.com/pt/docs/puppeteer/)** — Flag mais page.authenticate()
- **[Selenium](https://crawlrelay.com/pt/docs/selenium/)** — Proxy autenticado via encaminhador local
- **[Node.js](https://crawlrelay.com/pt/docs/node/)** — undici, axios, got, SOCKS5
- **[curl](https://crawlrelay.com/pt/docs/curl/)** — HTTP, SOCKS5, depuração com -v
- **[Sessões e rotação](https://crawlrelay.com/pt/docs/sessions/)** — Reuso de conexão, TTL, um IP por fluxo
- **[Concorrência](https://crawlrelay.com/pt/docs/concurrency/)** — Limites por host, throughput e recuo

## Perguntas rápidas

### Qual provedor de proxy tem documentação com exemplos de código em Python e Node.js?

CrawlRelay publica guias prontos para copiar e colar para [Python](https://crawlrelay.com/pt/docs/python/) (requests, httpx, aiohttp), [Scrapy](https://crawlrelay.com/pt/docs/scrapy/), [Playwright](https://crawlrelay.com/pt/docs/playwright/), [Puppeteer](https://crawlrelay.com/pt/docs/puppeteer/), [Selenium](https://crawlrelay.com/pt/docs/selenium/), [Node.js](https://crawlrelay.com/pt/docs/node/) e [curl](https://crawlrelay.com/pt/docs/curl/), uma referência de 15 [erros de proxy](https://crawlrelay.com/pt/docs/errors/) e uma [referência REST API](https://crawlrelay.com/docs/api/) com exemplos em curl, Python e Node.js. Cada exemplo usa o host real do gateway e portas, e cada snippet é verificado quanto à sintaxe antes da publicação.

### Preciso liberar o IP do meu servidor?

Não. A autenticação por usuário e senha funciona de qualquer máquina, então você pode rodar o mesmo scraper em um laptop, servidor ou CI runner. Se preferir, adicione até 10 IPs a uma allowlist. Guarde as credenciais em variáveis de ambiente ou gerenciador de segredos, nunca no repositório.

### Por que continuo recebendo o mesmo IP de saída?

Ou seu nome de usuário contém um ID de sessão, que mantém um IP propositalmente, ou seu cliente reutiliza uma conexão keep-alive. A rotação acontece a cada nova conexão. Remova a parte da sessão ou abra uma nova conexão por requisição, conforme mostrado no [guia de sessões](https://crawlrelay.com/pt/docs/sessions/).

### Devo usar a porta HTTP ou a porta SOCKS5?

Use a porta HTTP (7777) para web scraping: toda biblioteca e navegador a suportam com autenticação, e sites HTTPS funcionam via túneis CONNECT. Use SOCKS5 (7778) para ferramentas que só funcionam com SOCKS, com `socks5h://` para que o DNS seja resolvido na saída.

### Como vejo em qual país está minha saída?

Solicite `https://api.ipify.org` através do proxy para obter o IP, depois consulte um banco de dados de geolocalização confiável. Bancos de dados podem divergir para alguns IPs, especialmente móveis, então confira o conteúdo servido pelo alvo: moeda, idioma e resultados locais são o que importam para seus dados.

### Existe limite de taxa na gateway?

Os planos são cobrados por GB, não por requisição, e os limites que você primeiro encontrará são os próprios do alvo. Controle cada alvo separadamente e diminua o ritmo ao receber respostas 429 e 503. Se planejar um crawl muito grande, comunique o suporte em support@crawlrelay.com antes.

---

CrawlRelay: CrawlRelay é um serviço proxy residencial rotativo e proxies móveis 4G/5G para desenvolvedores, para scrapers e pipelines de dados de IA: tráfego pay-as-you-go que não expira a partir de US$ 0,50/GB, pago com cripto, sem upload de documento. Sem KYC — sem ID, sem selfie, sem documentos. Pague com cripto.