> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catproxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Обработка ошибок и коды ответов

> Узнайте о различных кодах HTTP-откликов, которые может возвращать наш прокси-шлюз, и научитесь устранять распространённые проблемы.

Когда вы делаете запрос через прокси-шлюз Catproxy, есть два потенциальных источника ошибок:

1. **Наш шлюз:** ошибки, связанные с вашей учётной записью, аутентификацией или конфигурацией прокси.
2. **Целевой сайт:** ошибки, возвращаемые сайтом, который вы пытаетесь парсить.

Чтобы помочь вам сразу отличить их друг от друга, наш шлюз добавляет специальный HTTP-заголовок к любой генерируемой им ошибке:

`X-Catproxy-Error: [понятное описание ошибки]`

**Правило: если вы видите заголовок `X-Catproxy-Error`, проблема связана с настройкой вашего прокси. Если нет, то проблема на стороне целевого сайта.**

***

## Ошибки шлюза (коды 4xx и 5xx)

Это ошибки, генерируемые нашей системой. Всегда проверяйте заголовок `X-Catproxy-Error`, чтобы узнать подробности.

### 400 Bad Request

Это означает, что вы ошиблись в настройке запроса.

| Сообщение `X-Catproxy-Error`                        | Значение и как исправить                                                                                                                    |
| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `Invalid username parameter: [param]`               | Вы использовали несуществующий параметр. Проверьте его написание в нашей документации.                                                      |
| `Conflicting targeting parameters...`               | Вы объединили взаимоисключающие параметры, например, `-country-us` и `-asn-123`. Выберите один метод таргетинга.                            |
| `Invalid value for parameter: [param]`              | Значение, которое вы указали, неверно (например, `-country-usa` вместо `-country-us`). Проверьте формат.                                    |
| `Missing required parameter...`                     | Вы использовали параметр, который зависит от другого параметра (например, `-state-ca` без `-country-us`). Добавьте необходимую зависимость. |
| `Ambiguous city name: [city]...`                    | Город, на который вы ориентируетесь, существует в нескольких штатах. Добавьте параметр `-state-[code]` для уточнения.                       |
| `Invalid format for header: X-Catproxy-Geolocation` | Синтаксис вашего геолокационного заголовка неверен. Проверьте формат `lat=...,lon=...,rad=...`.                                             |

### 407 Proxy Authentication Required

Это самая распространённая ошибка, которая всегда связана с вашими учётными данными или состоянием аккаунта.

| Сообщение `X-Catproxy-Error`         | Значение и как исправить                                                                                                   |
| :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `User authentication failed`         | Имя пользователя или пароль вашего прокси неверны. Дважды проверьте свои учётные данные.                                   |
| `IP address not whitelisted...`      | IP-адрес вашего сервера отсутствует в списке разрешённых IP-адресов для этого прокси. Добавьте его в настройках прокси.    |
| `Zero balance. Service suspended.`   | Баланс вашего аккаунта исчерпан. [**Пополните баланс**](https://catproxy.io/app/billing), чтобы снова активировать прокси. |
| `Traffic limit reached for proxy...` | Этот конкретный прокси превысил лимит использования, который вы настроили. Увеличьте лимит в настройках прокси.            |

### 502 Bad Gateway

Это указывает на временную проблему с конкретным резидентным IP, который был назначен для вашего запроса.

| Сообщение `X-Catproxy-Error`                       | Значение и как исправить                                                                                                                                                    |
| :------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `No available proxies for the requested target...` | В настоящее время у нас нет доступных IP, соответствующих вашим конкретным критериям таргетинга (например, очень маленький город). Попробуйте расширить таргетинг.          |
| `Session IP is offline`                            | IP-адрес вашей закреплённой сессии стал недоступен. **Просто повторите запрос с тем же идентификатором сессии**, чтобы получить новый IP (если вы не используете `-const`). |
| `Proxy connection failed`                          | Выбранный IP не смог подключиться к цели. Это временная сетевая проблема. **Повторите запрос.**                                                                             |

### 504 Gateway Timeout

Это означает, что соединение заняло слишком много времени.

| Сообщение `X-Catproxy-Error` | Значение и как исправить                                                                                                                                                   |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Target connection timeout`  | Наш прокси не смог установить соединение с целевым сайтом за разумное время. Возможно, целевой сайт не работает или блокирует запросы. Проверьте цель и повторите попытку. |
| `Proxy tunnel timeout`       | Возникли проблемы с сетью между нашим шлюзом и выходным IP. **Повторите запрос**, чтобы получить другой IP.                                                                |

***

## Ошибки целевого сайта

Если вы получили код ошибки **без** заголовка `X-Catproxy-Error`, это означает, что наш прокси успешно соединился с целью, но сама цель отклонила ваш запрос.

Вот наиболее распространённые ошибки, с которыми вы можете столкнуться при парсинге:

| HTTP-статус                   | Название            | Почему возникает и как исправить                                                                                                               |
| :---------------------------- | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| **403 Forbidden**             | Forbidden           | Целевой сайт определил ваш запрос как нечеловеческий и заблокировал ваш IP-адрес. **Действие: немедленно смените IP.**                         |
| **429 Too Many Requests**     | Rate Limited        | Вы отправляете запросы слишком быстро. **Действие: замедлите работу парсера** (увеличьте задержки) и смените IP.                               |
| **500 Internal Server Error** | Server Error        | На сервере целевого сайта возникла внутренняя проблема. **Действие: повторите запрос после небольшой задержки.**                               |
| **503 Service Unavailable**   | Service Unavailable | Целевой сайт перегружен или отключен для обслуживания. **Действие: повторите запрос после более длительной задержки (например, 15-30 минут).** |