Catproxy Developer Documentation

Чтобы пользоваться нашей прокси-сетью, каждый запрос, который вы отправляете на прокси-шлюз, должен быть аутентифицирован. Это гарантирует, что только авторизованные пользователи могут получить доступ к сервису и что мы сможем правильно отнести использование трафика к вашей учётной записи. Мы предлагаем два метода аутентификации:

Имя пользователя и пароль

Самый распространённый метод. Вы включаете уникальные учётные данные вашего прокси в каждый запрос.

Разрешённые IP-адреса (скоро)

Более простой метод для серверов. Вы предварительно авторизуете IP-адрес своего сервера, позволяя ему подключаться без отправки учётных данных.

1. Аутентификация по имени пользователя и паролю

Это стандартный и наиболее гибкий метод аутентификации. Каждый прокси, который вы создаёте в панели управления, имеет свое уникальное имя пользователя и пароль.

Как это работает

Вам нужно включить эти учётные данные в строку подключения к прокси в следующем формате: protocol://username:password@host:port В качестве протокола используйте https. Он шифрует канал между вашей программой и нашим шлюзом, поэтому пароль от прокси никогда не передаётся в читаемом виде. Подробности и список инструментов, которые так не умеют, - в разделе Протоколы.

Пример

Допустим, ваши учётные данные:

Имя пользователя: cat-customer-a1b2-proxy-steam
Пароль: a_very_secure_password
Хост и порт: proxy.catproxy.net:5555

Ваша строка подключения будет выглядеть так:

https://cat-customer-a1b2-proxy-steam:a_very_secure_password@proxy.catproxy.net:5555

# Подключение через cURL
curl "https://api.ipify.org" \
  --proxy "https://cat-customer-a1b2-proxy-steam:a_very_secure_password@proxy.catproxy.net:5555"

# Подключение через библиотеку Requests
import requests

proxy = "https://cat-customer-a1b2-proxy-steam:a_very_secure_password@proxy.catproxy.net:5555"

proxies = {
    "http": proxy,
    "https": proxy,
}

response = requests.get("https://api.ipify.org", proxies=proxies)
print(response.text)

// Подключение через Axios
const axios = require('axios');

const { data } = await axios.get("https://api.ipify.org", {
  proxy: {
    protocol: 'https',
    host: 'proxy.catproxy.net',
    port: 5555,
    auth: {
      username: 'cat-customer-a1b2-proxy-steam',
      password: 'a_very_secure_password',
    },
  },
});

console.log(data);

Помните, что вы можете динамически добавлять параметры вроде -country-de к своему имени пользователя, чтобы контролировать поведение прокси. Узнайте больше в руководстве по параметрам геотаргетинга.

Пароли со специальными символами

Если пароль от прокси содержит @, :, #, / или ?, подстановка его прямо в строку подключения ломает разбор URL, и запрос падает с непонятной ошибкой. Передавайте учётные данные отдельно:

curl "https://api.ipify.org" \
  --proxy "https://proxy.catproxy.net:5555" \
  --proxy-user "cat-customer-a1b2-proxy-steam:a_very_secure_password"

В большинстве библиотек есть аналог: отдельный аргумент для аутентификации или процентное кодирование пароля перед сборкой URL (urllib.parse.quote в Python, encodeURIComponent в JavaScript).

2. Разрешённые IP-адреса (авторизованные IP) (скоро)

Этот метод идеально подходит для серверов или любых машин со статическим IP-адресом. Добавив свой IP в список разрешённых IP-адресов, вы сможете отправлять запросы без встраивания учётных данных в код. При этом по сети не передаётся ничего, что можно было бы перехватить, - это самый безопасный из доступных вариантов.

Как это работает

Добавьте свой IP: на странице настроек вашего прокси перейдите в раздел “Управление доступом” и добавьте IP-адрес вашего сервера (например, 34.123.45.67) в список Разрешённые IP-адреса.
Подключайтесь без учётных данных: теперь любой запрос, поступающий с этого IP-адреса на host:port вашего прокси, будет автоматически аутентифицирован.

Пример

Предположим, что IP-адрес вашего сервера 34.123.45.67 был внесён в список разрешённых IP-адресов для прокси по адресу proxy.catproxy.net:5555.

# Имя пользователя и пароль не нужны!
curl "https://api.ipify.org" \
  --proxy "https://proxy.catproxy.net:5555"

# Словарь proxies теперь намного проще
import requests

proxy = "https://proxy.catproxy.net:5555"

proxies = {
    "http": proxy,
    "https": proxy,
}

response = requests.get("https://api.ipify.org", proxies=proxies)
print(response.text)

Важно: Разрешённые IP-адреса работает только для IPv4-адресов. Если ваш сервер имеет динамический IP, вы должны использовать метод имени пользователя и пароля.

Какой метод использовать?

Сценарий	Рекомендуемый метод
Запуск скриптов с локальной машины (динамический IP)	Имя пользователя и пароль
Запуск скриптов на облачном сервере (статический IP)	Разрешённые IP-адреса
Использование инструмента, который не поддерживает аутентификацию через прокси	Разрешённые IP-адреса
Нужна максимальная гибкость и контроль	Имя пользователя и пароль

3. Диагностика

Когда шлюз отклоняет подключение, он возвращает заголовок X-Proxy-Error с точной причиной. Запустите запрос в подробном режиме и сначала прочитайте этот заголовок:

curl -v "https://api.ipify.org?format=json" \
  --proxy "https://proxy.catproxy.net:5555" \
  --proxy-user "ВАШ_USERNAME:ВАШ_ПАРОЛЬ"

Что вы видите	Что это значит
`407` и `X-Proxy-Error: all parameters missing`	До шлюза не дошли учётные данные. Проверьте, что клиент действительно отправляет аутентификацию для прокси.
`X-Proxy-Error: parameter missing`, `invalid parameter` или `unknown parameter`	Параметр таргетинга в имени пользователя отсутствует, записан неверно или содержит опечатку. См. параметры геотаргетинга.
`X-Proxy-Error: dependency missing`	Параметр требует другого параметра. Например, `city` требует `country`.
`X-Proxy-Error: parameter conflict`	Два параметра нельзя использовать вместе. Например, `asn` не сочетается с `country`.
Ошибка TLS или протокола сразу после подключения	Ваш клиент не поддерживает HTTPS-прокси. Переключите протокол на `HTTP` - см. Протоколы.
Запрос завершается таймаутом вообще без ответа	Исходящий трафик на этот порт блокируется вашей сетью. См. Таймауты и отказ в подключении.

Если для одних адресов запросы проходят, а для других нет, проверьте на прокси списки Разрешённые хосты и Разрешённые IP-адреса: если любой из них заполнен, все остальное отклоняется.

Начало работы

Руководства

Прокси-продукты

Гео-справочники

Решение проблем

Правовая информация

Примечания к выпуску

Методы аутентификации

Имя пользователя и пароль

Разрешённые IP-адреса (скоро)

1. Аутентификация по имени пользователя и паролю

Как это работает

Пример

Пароли со специальными символами

2. Разрешённые IP-адреса (авторизованные IP) (скоро)

Как это работает

Пример

Какой метод использовать?

3. Диагностика

Имя пользователя и пароль

Разрешённые IP-адреса (скоро)

​1. Аутентификация по имени пользователя и паролю

​Как это работает

​Пример

​Пароли со специальными символами

​2. Разрешённые IP-адреса (авторизованные IP) (скоро)

​Как это работает

​Пример

​Какой метод использовать?

​3. Диагностика

1. Аутентификация по имени пользователя и паролю

Как это работает

Пример

Пароли со специальными символами

2. Разрешённые IP-адреса (авторизованные IP) (скоро)

Как это работает

Пример

Какой метод использовать?

3. Диагностика