Ошибки API

Каждый эндпоинт под https://litport.net/api/v1 (Токены, Пакеты и Оплата за ГБ) возвращает ошибки в формате JSON, описанном на этой странице. Сбои самого проксируемого соединения используют отдельные числовые коды ошибок прокси, а публичный API бесплатных прокси здесь не рассматривается.

Формат ошибки#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication failed.",
    "requestId": "req_example",
    "docsUrl": "https://litport.net/docs/api/errors"
  }
}

Тот же ID запроса передаётся в заголовке X-Request-ID. Записывайте его в лог вместе с HTTP-статусом и кодом ошибки. Никогда не записывайте в лог заголовок Authorization.

409 с ожиданием также добавляет nextChangeAt — метку времени ISO-8601 в UTC: это CHANGE_LIMIT при смене локации токена или получении нового IP.

Справочник статусов#

Статус	Коды	Действие клиента
`400`	`INVALID_REQUEST_BODY`, `INVALID_LIMIT`, `INVALID_CURSOR`, `INVALID_TYPE`, `INVALID_STATUS`, `INVALID_PACKAGE_ID`, `INVALID_TIME_RANGE`, `INVALID_GROUP_BY`, `INVALID_INCLUDE`, `INVALID_POOL`, `INVALID_LEVEL`, `INVALID_PARENT`, `GEO_NOT_ENABLED`, `GEO_LEVEL_UNSUPPORTED`, `INVALID_IP`, `IPV6_UNSUPPORTED`, `INVALID_LOCATION`, `INVALID_ROTATION`	Исправьте запрос. Не повторяйте его без изменений.
`401`	`UNAUTHORIZED`	Передайте действующий API-ключ по схеме Bearer. Ответ не раскрывает, существует ли ключ или пользователь.
`404`	`TOKEN_NOT_FOUND`, `PACKAGE_NOT_FOUND`	Проверьте ID и принадлежность. Ответ не раскрывает токен или пакет другого пользователя.
`404`	`NOT_FOUND`	Исправьте маршрут: он не существует.
`405`	`METHOD_NOT_ALLOWED`	Используйте один из методов из заголовка `Allow`.
`409`	`NOT_SUPPORTED`, `PACKAGE_INACTIVE`, `CONCURRENT_CHANGE`, `LOCATION_UNAVAILABLE`, `CHANGE_LIMIT`, `ALLOWED_IPS_LIMIT_REACHED`	См. соответствующее описание ниже; `CONCURRENT_CHANGE` означает, что нужно повторить тот же запрос, `CHANGE_LIMIT` — что нужно дождаться указанного `nextChangeAt`.
`413`	`INVALID_REQUEST_BODY`	Тело превышает 4 КиБ. Отправьте тело меньшего размера.
`415`	`INVALID_CONTENT_TYPE`	Для записи с телом отправляйте `Content-Type: application/json`.
`429`	`RATE_LIMITED`	Учитывайте `Retry-After` и используйте экспоненциальную задержку с джиттером.
`503`	`SERVICE_UNAVAILABLE`, `TOKEN_DATA_INVALID`, `ALLOWED_IPS_UNAVAILABLE`	Учитывайте `Retry-After`, повторяйте с ограниченной экспоненциальной задержкой, затем обратитесь в поддержку, указав ID запроса.

Алгоритм повторов#

Автоматически повторяйте 429 и 503, учитывая Retry-After и добавляя джиттер, кроме 503 на POST /tokens/{tokenId}/new-ip (см. ниже). Ограничьте число попыток и сделайте общий бюджет повторов видимым для вызывающей стороны.

Любую запись в этом API можно безопасно повторять, кроме new-ip: 409 CONCURRENT_CHANGE или неоднозначный ответ (тайм-аут, потерянный ответ, 503) можно просто отправить снова, потому что последняя запись всегда побеждает, а любая другая запись ничего не меняет, если уже применена. Для new-ip неоднозначный результат означает, что сначала нужно прочитать GET /tokens/{tokenId}/location и повторять, только если nextChangeAt ещё не позже текущего времени. Слепой повтор в течение недели вернёт только 409 CHANGE_LIMIT.

Подробности по кодам ошибок#

Недопустимое тело запроса#

400, если тело не разбирается как JSON или не проходит собственную проверку структуры эндпоинта (например, PUT /tokens/{tokenId}/rotation требует ровно {"intervalSec": <integer>}). 413, если тело превышает 4 КиБ.

Недопустимый тип содержимого#

INVALID_CONTENT_TYPE означает, что запись с телом отправлена без Content-Type: application/json.

Недопустимый лимит#

INVALID_LIMIT означает, что limit — не целое число от 1 до 100 включительно.

Недопустимый курсор#

INVALID_CURSOR означает, что непрозрачный курсор имеет неверный формат, изменён, не проходит проверку подлинности или выдан для другого эндпоинта. Начните пагинацию заново без курсора.

Недопустимый тип#

INVALID_TYPE означает, что type в GET /tokens не является ни unlimited, ни ppg.

Недопустимый статус#

INVALID_STATUS означает, что status в GET /tokens не является одним из значений active, expired или disabled.

Недопустимый ID пакета#

INVALID_PACKAGE_ID означает, что фильтр packageId в GET /tokens — не положительное целое число. packageId в пути URL никогда не даёт 400: неизвестный или чужой даёт 404 PACKAGE_NOT_FOUND.

Недопустимый диапазон времени#

INVALID_TIME_RANGE означает, что метка времени не в каноническом UTC, from не раньше to или запрошенный интервал слишком велик.

Недопустимая группировка#

INVALID_GROUP_BY означает, что groupBy не является одним из значений hour, day или month.

Недопустимое расширение#

INVALID_INCLUDE означает, что запрошенное расширение несовместимо с токеном или группировкой; компоненты списаний требуют PPG-токена и почасовых интервалов.

Недопустимый пул#

INVALID_POOL означает, что pool в GET /pay-per-gb/geo отсутствует, пуст или содержит ключ авторизации, который не соответствует пулу, доступному для выбора клиентом.

Недопустимый уровень#

INVALID_LEVEL означает, что level — не одно из значений, которые принимает эндпоинт: region/city для вариантов локации токена или country/region/city для гео оплаты за ГБ.

Недопустимый родительский объект#

INVALID_PARENT означает, что отсутствует обязательная родительская география: для location/options?level=city токена нужен region; для GET /pay-per-gb/geo нужен country при level=region и при level=city.

Геотаргетинг не включён#

GEO_NOT_ENABLED означает, что у запрошенного пула геотаргетинг выключен.

Уровень гео не поддерживается#

GEO_LEVEL_UNSUPPORTED означает, что запрошенный пул не поддерживает запрошенный level. Проверьте geoLevels пула на странице Оплата за ГБ.

Недопустимый IP#

INVALID_IP означает, что переданный адрес — не точный публичный литерал IPv4.

IPv6 не поддерживается#

IPV6_UNSUPPORTED означает, что IPv6-адрес отправлен в запись разрешённых IP пакета; обратитесь в поддержку.

Недопустимая локация#

INVALID_LOCATION означает, что запрошенный регион, город или оператор — не то значение, которое может использовать этот токен, либо country передан со значением, отличным от "us".

Недопустимая ротация#

INVALID_ROTATION означает, что intervalSec в PUT /tokens/{tokenId}/rotation не входит в перечисленные options токена.

Не авторизован#

UNAUTHORIZED охватывает отсутствующие, неверно сформированные, неизвестные, прошедшие ротацию и не имеющие владельца ключи, не раскрывая, какой именно случай имел место.

Токен не найден#

TOKEN_NOT_FOUND охватывает отсутствующий, не принадлежащий вам или не поддающийся разбору tokenId в любом маршруте токена. Ответ одинаков во всех случаях, поэтому он никогда не раскрывает токен другого пользователя.

Пакет не найден#

PACKAGE_NOT_FOUND охватывает отсутствующий, не принадлежащий вам или не поддающийся разбору packageId в любом маршруте пакета, включая разрешённые IP пакета.

Не найдено#

NOT_FOUND означает, что запрошенного маршрута /api/v1 не существует.

Метод не разрешён#

METHOD_NOT_ALLOWED означает, что известный эндпоинт получил неподдерживаемый метод. Ответ содержит его поддерживаемые методы в Allow.

Не поддерживается#

NOT_SUPPORTED означает, что у этого токена нет такой возможности: его локацию нельзя изменить, его интервал ротации нельзя изменить или (new-ip) это не статический серверный или ISP-прокси. Для токена «Мультилокация» интервал ротации всегда отвечает NOT_SUPPORTED, потому что его задаёт телефон, на котором работает прокси.

Пакет неактивен#

PACKAGE_INACTIVE означает, что оплаченный период токена или пакета сейчас не активен.

Одновременное изменение#

CONCURRENT_CHANGE означает, что другая запись в тот же токен или пакет прошла в тот же момент. Повторите тот же запрос.

Локация недоступна#

LOCATION_UNAVAILABLE означает, что у запрошенной локации сейчас нет доступного IP или рабочего устройства. Ничего не изменилось.

Лимит изменений#

CHANGE_LIMIT означает, что лимит на изменение или замену уже исчерпан: раз в неделю для нового IP или смены локации статического серверного/ISP-прокси, раз в 48 часов для смены локации стандартного US Shared Mobile. Ошибка содержит nextChangeAt и соответствующий Retry-After.

Достигнут лимит разрешённых IP#

ALLOWED_IPS_LIMIT_REACHED означает, что список разрешённых IP пакета уже достиг своего limit (1 или 50). Обратитесь в поддержку, чтобы увеличить его.

Ограничено по частоте#

RATE_LIMITED означает, что API-ключ или, для записи разрешённых IP, пакет исчерпал текущее окно. Учитывайте Retry-After.

Сервис недоступен#

SERVICE_UNAVAILABLE означает, что зависимость API временно недоступна. Учитывайте Retry-After.

Недопустимые данные токена#

TOKEN_DATA_INVALID означает, что сохранённые метаданные токена временно нечитаемы. Повторите позже, затем сообщите ID запроса.

Разрешённые IP недоступны#

ALLOWED_IPS_UNAVAILABLE означает, что хранилище разрешённых IP, конфигурация или выделение портов недоступны, в том числе когда у пакета временно закончились назначаемые порты.

Сбои аутентификации#

API намеренно возвращает один и тот же ответ 401 для неверно сформированных, неизвестных, прошедших ротацию и не имеющих владельца ключей. Создайте API-ключ или выполните его ротацию на странице Настройки. Ротация сразу делает недействительным предыдущий активный ключ.

Markdown OpenAPI

Начало

Основы прокси

API для прокси

Кеш ответов

Litport API

MCP-сервер