Ошибки API

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

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

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

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

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

retryable есть всегда и равен true или false. true означает, что тот же запрос, отправленный снова без изменений после Retry-After (или nextChangeAt, если он есть в ошибке), может завершиться успешно, и его безопасно отправить повторно: ничего не было сделано (RATE_LIMITED, CONCURRENT_CHANGE, CHANGE_LIMIT, ALLOWANCE_CONFLICT) или это 503 на запрос, который можно безопасно повторять. false означает, что сначала нужно что-то изменить: запрос, аккаунт или токен. 503 на запрос, который небезопасно повторять, — тоже false: прочитайте текущее состояние, прежде чем решать (см. Алгоритм повторов).

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

Статус	Коды	Действие клиента
`400`	`INVALID_REQUEST_BODY`, `INVALID_LIMIT`, `INVALID_CURSOR`, `INVALID_TYPE`, `INVALID_STATUS`, `INVALID_PACKAGE_ID`, `INVALID_TOKEN_IDS`, `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`, `INVALID_LABEL`, `INVALID_EXTERNAL_REF`, `INVALID_REQUEST_ID`, `INVALID_ENABLED`, `INVALID_EXPIRY`, `INVALID_ALLOWANCE`, `FIELD_NOT_ALLOWED`	Исправьте запрос. Не повторяйте его без изменений.
`401`	`UNAUTHORIZED`	Передайте действующий API-ключ по схеме Bearer. Ответ не раскрывает, существует ли ключ или пользователь.
`402`	`INSUFFICIENT_BALANCE`	Пополните баланс и отправьте запрос снова. Баланс нужен только для создания прокси и его включения.
`403`	`ACCOUNT_BANNED`	Пока аккаунт заблокирован, создавать прокси и включать его нельзя. Обратитесь в поддержку.
`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`, `NOT_IN_FALLBACK`, `CHANGE_LIMIT`, `ALLOWED_IPS_LIMIT_REACHED`, `TOKEN_LIMIT_REACHED`, `TOKEN_NOT_EDITABLE`, `ALLOWANCE_CONFLICT`, `POOL_REQUIRED_FOR_IP_AUTH`	См. соответствующее описание ниже; `CONCURRENT_CHANGE` и `ALLOWANCE_CONFLICT` означают, что нужно повторить тот же запрос, `CHANGE_LIMIT` — что нужно дождаться указанного `nextChangeAt` и повторить; у всех трёх `retryable: true`.
`413`	`INVALID_REQUEST_BODY`	Тело превышает 4 КиБ. Отправьте тело меньшего размера.
`415`	`INVALID_CONTENT_TYPE`	Для записи с телом отправляйте `Content-Type: application/json`.
`429`	`RATE_LIMITED`	Учитывайте `Retry-After` и используйте экспоненциальную задержку с джиттером. `retryable` равен `true`.
`503`	`SERVICE_UNAVAILABLE`, `TOKEN_DATA_INVALID`, `ALLOWED_IPS_UNAVAILABLE`	Учитывайте `Retry-After`. Повторяйте с ограниченной экспоненциальной задержкой, когда `retryable` равен `true`, затем обратитесь в поддержку, указав ID запроса.

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

Повторяйте автоматически, только когда retryable равен true: подождите Retry-After (и до nextChangeAt, если он есть в ошибке), добавьте джиттер и отправьте тот же запрос снова. Ограничьте число попыток и сделайте общий бюджет повторов видимым для вызывающей стороны. Если retryable равен false, сначала что-нибудь измените или — после неясного сбоя запроса, который небезопасно повторять (см. ниже), — прочитайте текущее состояние, прежде чем решать.

Любую запись в этом API можно безопасно повторять, кроме new-ip, POST /tokens без externalRef, POST /tokens/{tokenId}/credentials без requestId, PUT /tokens/{tokenId}/location с {"random": true} и двух POST-запросов API поддержки (POST /support/conversations и POST /support/conversations/{conversationId}/messages). Любую другую запись, получившую 409 CONCURRENT_CHANGE или неоднозначный ответ (тайм-аут, потерянный ответ, 503), можно просто отправить снова, потому что последняя запись всегда побеждает, а любая другая запись ничего не меняет, если уже применена. 503 на запрос, который небезопасно повторять, приходит с retryable: false, потому что работа могла быть выполнена до сбоя.

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

Создание можно безопасно повторить, если в нём есть externalRef: повтор вернёт уже существующий прокси. Без него повтор может создать второй прокси. Перевыпуск можно безопасно повторить, если в нём есть requestId: повтор вернёт данные для подключения, выданные первым вызовом. Без него повтор выдаёт новую пару. См. Создание и управление прокси.

У токена с ротацией new-ip нельзя проверить через GET /tokens/{tokenId}/location: его canChangeNow и nextChangeAt относятся к местоположению и ничего не говорят об ожидании между новыми IP. Повторная отправка после Retry-After безвредна: она просто даёт ещё один новый IP. 409 CHANGE_LIMIT сразу после потерянного ответа не доказывает, что смена прошла, потому что ответ 409 LOCATION_UNAVAILABLE тоже расходует ожидание.

PUT /tokens/{tokenId}/location с {"random": true} каждый раз выбирает новую локацию, поэтому повтор снова перемещает прокси везде, где нет ожидания. После потерянного ответа сначала прочитайте GET /tokens/{tokenId}/location и отправляйте запрос снова, только если прокси не там, где вам нужно. У двух POST-запросов API поддержки нет ключа идемпотентности, а 503 может прийти уже после того, как сообщение сохранено: прочитайте диалог, прежде чем отправлять сообщение снова.

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

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

400, если тело не разбирается как JSON или не проходит собственную проверку структуры эндпоинта (например, PUT /tokens/{tokenId}/rotation требует ровно {"intervalSec": <integer>}). В POST /tokens, PATCH /tokens/{tokenId} и POST /tokens/{tokenId}/credentials тело должно быть JSON-объектом, содержащим только поля, которые принимает этот вызов, а для PATCH нужно хотя бы одно. 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_TOKEN_IDS означает, что tokenIds в GET /usage — не список положительных ID прокси либо в нём больше 100 ID.

Недопустимый 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, POST /tokens или PATCH /tokens/{tokenId} отсутствует там, где он обязателен, пуст или содержит ключ авторизации, который не соответствует пулу, доступному для выбора клиентом.

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

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 токена.

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

INVALID_LABEL означает, что label — не текст длиной до 255 символов и не null (чтобы очистить метку).

Недопустимая внешняя ссылка#

INVALID_EXTERNAL_REF означает, что externalRef — не строка из 1–128 печатаемых символов.

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

INVALID_REQUEST_ID означает, что requestId в POST /tokens/{tokenId}/credentials — не строка из 1–64 символов: букв, цифр, подчёркивания или дефиса.

Недопустимое включение#

INVALID_ENABLED означает, что enabled — не true и не false.

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

INVALID_EXPIRY означает, что expiresAt — не дата и время ISO 8601 с часовым поясом, не дата, которая ещё впереди, и не null.

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

INVALID_ALLOWANCE означает, что allowanceBytes — не целое число не меньше 1 (байт) и не null (чтобы снять лимит).

Поле не разрешено#

FIELD_NOT_ALLOWED означает, что PATCH /tokens/{tokenId} отправил для прокси пакета поле, отличное от label. Прокси пакета включаются и выключаются самим пакетом.

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

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, потому что его задаёт телефон, на котором работает прокси. DELETE /tokens/{tokenId} для прокси пакета тоже отвечает этим кодом: удалять можно только прокси с оплатой за ГБ.

Недостаточный баланс#

INSUFFICIENT_BALANCE — это 402. Для создания прокси и его включения нужен положительный баланс. Всё остальное работает и при пустом балансе: выключение, смена метки, смена срока действия или лимита, перевыпуск данных для подключения и удаление.

Аккаунт заблокирован#

ACCOUNT_BANNED — это 403. Заблокированный аккаунт не может создать прокси или включить его. Выключение, перевыпуск данных для подключения и удаление по-прежнему работают. Обратитесь в поддержку.

Достигнут лимит токенов#

TOKEN_LIMIT_REACHED означает, что в аккаунте уже максимально допустимое число прокси с оплатой за ГБ. Удалите ненужный прокси или обратитесь в поддержку, чтобы увеличить лимит.

Токен нельзя изменить#

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

Конфликт лимита трафика#

ALLOWANCE_CONFLICT означает, что лимит трафика не удалось сохранить. Ничего не изменилось. Отправьте тот же запрос ещё раз.

Для входа по IP нужен пул#

POOL_REQUIRED_FOR_IP_AUTH означает, что pool: null отправлен для прокси, который входит по разрешённому IP. Этот прокси сохраняет один пул.

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

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

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

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

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

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

Не в состоянии fallback#

NOT_IN_FALLBACK — ответ на POST /tokens/{tokenId}/location/return, когда токен не находится вне сохранённой локации, так что возвращать нечего. Повтор запроса, который уже сработал, попадает сюда и не выдаёт второй IP. Ничего не изменилось.

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

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

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

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

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

RATE_LIMITED означает, что API-ключ (для GET /usage — его собственное ограничение в 10 запросов за 60 секунд), для записи разрешённых IP — пакет, а для POST /tokens — аккаунт (его лимит на создание новых прокси в минуту, общий для всех его ключей и личного кабинета), исчерпал текущее окно. Ничего не было сделано. Учитывайте Retry-After; retryable равен true.

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

SERVICE_UNAVAILABLE означает, что зависимость API временно недоступна. Учитывайте Retry-After. retryable равен false, когда запрос небезопасно повторять; см. Алгоритм повторов.

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

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

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

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

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

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

Markdown OpenAPI

Начало

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

API для прокси

Кеш ответов

Litport API

MCP-сервер