# Коди помилок

На цій сторінці перелічено основні коди помилок, які повертає API MoreLogin.

## Формат відповіді

Усі відповіді API мають такий стандартний вигляд:

```json
{
  "code": 0,
  "msg": null,
  "data": {},
  "requestId": "unique-request-id"
}
```

| Поле | Тип | Опис |
|  --- | --- | --- |
| `code` | integer | `0` = успіх, `>0` = помилка |
| `msg` | string | Повідомлення про помилку (null у разі успіху) |
| `data` | object | Дані відповіді |
| `requestId` | string | Унікальний ідентифікатор запиту для діагностики |


## Як за кодом визначити область

Коди не видаються з одного суцільного списку. Кожна продуктова область має власний діапазон, тому перші дві або три цифри показують, яка підсистема відхилила запит:

| Діапазон | Область |
|  --- | --- |
| `14xxx` | Проксі |
| `15xxx` | Групи та мітки |
| `19xxx` | Профілі браузера |
| `20xxx` | Гаманець, замовлення та тарифікація |
| `21001` | Занадто стара версія клієнта |
| `33xxx` | Хмарний телефон |
| `35xxx` | Автентифікація API та обмеження частоти |
| `39xxx` | Хмарне сховище |
| `40xxx` | Середовища виконання хмарного браузера |
| `41xxx` | Налаштування вебхуків |
| `99xxx` | Шлюз і перевірка запиту |


Для кожної операції перелічено коди, які вона напевно може повернути. Див. попродуктові матриці за посиланнями з [матриці повторів і завершення ендпоінтів](/uk/api-reference/getting-started/endpoint-behavior).

## Загальні коди помилок

Можуть повернутися з будь-якої операції, бо походять із перевірки запиту, перевірки прав і шлюзу, а не з бізнес-логіки.

| Код | Опис | Що робити |
|  --- | --- | --- |
| `0` | Успіх | — |
| `21001` | Занадто стара версія клієнта | Оновіть десктопний клієнт MoreLogin |
| `35000` | Занадто часті запити до API | Повторюйте придатні операції з відступом і дрижанням; див. [Обмеження частоти](/uk/api-reference/getting-started/rate-limits) |
| `99000` | Невідома системна помилка | Повторіть пізніше та повідомте `requestId` підтримці |
| `99001` | Недопустимі параметри запиту | Перевірте формат тіла запиту та обовʼязкові поля |
| `99002` | Немає прав на операцію | Перевірте права свого акаунта |
| `99003` | Виняток у запиті | Внесіть потрібну бізнес-правку згідно з `msg` |
| `99004` | Тіло запиту занадто велике | Зменште тіло запиту |
| `99005` | Такий запит уже виконується | Дочекайтеся завершення поточного запиту й повторіть |
| `99006` | Некоректний запит | Перевірте HTTP-метод, заголовки та тіло |
| `99007` | IP запиту не в списку дозволених | Додайте IP того, хто викликає, до списку дозволених |
| `99008` | Перевищено квоту запитів для IP або пристрою | Зменште кількість запитів із цього IP або пристрою |
| `99009` | Занадто багато запитів | Відступіть із дрижанням і повторіть |
| `99011` | Позначка часу запиту протермінована | Надішліть заново з поточною позначкою часу |
| `99012` | Потрібне право на витрати | Скористайтеся акаунтом власника команди або видайте право на витрати |


### Хмарний телефон (`33xxx`)

| Код | Опис | Що робити |
|  --- | --- | --- |
| `20002` | The original monthly order was cancelled | Create a new monthly purchase for eligible Cloud Phones |
| `20003` | The original monthly order was refunded | Create a new monthly purchase for eligible Cloud Phones |
| `20004` | The original monthly order does not exist | Verify the Cloud Phone purchase state and contact support with `requestId` if it persists |
| `20008` | The original monthly order is not completed or its status cannot be confirmed | Check the order and Cloud Phone state before retrying |
| `20055` | A Cloud Phone does not exist, was deleted, or does not belong to the team | Verify every Cloud Phone ID and team ownership |
| `20068` | A pending monthly payment order already exists | Complete or cancel the pending order before using the activation API |
| `20070` | A concurrent Cloud Phone purchase is already in progress | Wait for the in-flight purchase to settle, then read state before retrying |
| `20071` | A selected monthly SKU is unavailable or has no active 30-day price | Query the monthly SKU endpoint again and choose an available product |
| `33420` | Paid and unpaid Cloud Phones cannot be activated in the same batch | Separate Cloud Phones by purchase state and submit compatible batches |
| `33421` | Paid Cloud Phones from different purchase orders cannot be mixed | Submit one activation batch per original purchase order |
| `33422` | Payment succeeded but activation is incomplete or cannot yet be confirmed | Inspect `data.results` and each Cloud Phone's expiry state; do not pay again blindly |
| `33300` | Хмарний телефон не існує | Перевірте ID хмарного телефона та чи належить він вашій команді |
| `33301` | Хмарний телефон не увімкнено | Увімкніть його та дочекайтеся працездатного стану |
| `33308` | Використовується іншим учасником, вимкнути неможливо | Повторіть, коли інший учасник звільнить його |
| `33309` | Використовується іншим учасником, підключитися неможливо | Повторіть, коли інший учасник звільнить його |
| `33315` | Заборгованість на рахунку, хмарний телефон заморожено | Поповніть гаманець |
| `33316` | Недостатньо доступних профілів | Оновіть тариф |
| `33317` | Право на профіль було відкликано | Попросіть адміністратора видати доступ |
| `33318` | Недостатньо коштів для запуску | Поповніть гаманець |
| `33321` | Профіль недоступний | Перед повтором перевірте стан профілю |
| `33322` | Триває перевірка проксі | Опитуйте, доки перевірка не завершиться |
| `33323` | Профіль запускається | Дочекайтеся завершення запуску, повторно не надсилайте |
| `33324` | Профіль уже запущений | Нічого робити не потрібно |
| `33325` | Профіль деактивовано | Активуйте його перед використанням |
| `33331` | Триває зміна пристрою в один клік, вимкнути неможливо | Дочекайтеся завершення |
| `33332` | Триває перезавантаження, вимкнути неможливо | Дочекайтеся завершення |
| `33333` | Триває скидання, вимкнути неможливо | Дочекайтеся завершення |
| `33338`–`33345` | Країна, часовий пояс, мова, довгота або широта відсутні чи недопустимі | Див. [таблицю країн і часових поясів](/uk/api-reference/appendix/country-time-zone) |
| `33346` | SKU знято з продажу | Виберіть інший `skuId` |
| `33347` | Модель потребує найновішої версії клієнта для Windows | Оновіть десктопний клієнт MoreLogin |
| `33367` | Триває обслуговування, увімкнути неможливо | Терміни відновлення дивіться в системних повідомленнях |
| `33376` | Місячна тарифікація завершилася | Продовжте підписку |
| `33398`–`33400` | Довгота, широта або висота поза діапазоном | Довгота −180…180, широта −90…90, висота −50000…100000 |
| `33401` | Хмарний телефон не підтримує цю операцію | Використовуйте підтримувану модель |
| `33407` | Перевищено квоту пакета паралельних запусків | Дочекайтеся вільного слота або збільште квоту |
| `33408` | Недопустимий формат номера телефона | Починайте з `+`, код країни 1–3 цифри без 86, загалом 8–14 цифр |
| `33418` | Файл для трансляції не існує або недопустимий | Вивантажте з `uploadType=2` і використайте повернений `fileId` |
| `33419` | Формат файлу для трансляції не підтримується | Вивантажте MP4 через `/cloudphone/uploadFile` |
| `33005` | Не вдалося встановити застосунок | Повторіть і перевірте вільне місце на пристрої |
| `33014` | Занадто часті операції | Відступіть і повторіть |
| `33714` | Застосунок не існує або знято з публікації | Оновіть бібліотеку застосунків |
| `33814` | Шаблон RPA не існує | Запросіть список шаблонів заново та використайте актуальний `templateId` |
| `33818` | Недопустимий формат параметра шаблону RPA | Передавайте `templateParameter` як екранований JSON-рядок |
| `33303` | Не вдалося створити хмарний телефон | Перед повтором запитайте `/cloudphone/page`; не надсилайте наосліп |
| `33320` | Проксі, привʼязаний до цього хмарного телефона, видалено | Привʼяжіть проксі заново через `/cloudphone/setProxy` |
| `33326` | Використовується іншим учасником, замінити пристрій неможливо | Повторіть, коли інший учасник звільнить його |
| `33350` | На частині хмарних телефонів не вдалося увімкнути ADB | Ці телефони не запущені або не підтримують ADB; перечитайте стан і повторіть лише для них |
| `33507` | Файл на пристрої не існує | Перевірте шлях; запит на завантаження спершу обходить батьківський каталог |


Операції встановлення та керування живленням можуть додатково повернути код, зіставлений Сервісом, із діапазонів `33001`–`33033`, `33500`–`33520`, `33700`–`33724` або `33900`–`33910`. Який із них досяжний, залежить від Сервіса, що обслуговує пристрій, тому в операціях вони не перелічені окремо.

### Профілі браузера (`19xxx`)

| Код | Опис | Що робити |
|  --- | --- | --- |
| `19001` | Профіль із такою назвою вже існує | Виберіть унікальну назву або опустіть `envName`, щоб її згенерували |
| `19002` | Створення профілю не вдалося на боці сервісу | Перед повтором підтвердьте через `/env/page` |
| `19004` | Недопустимий формат user agent | Передайте `advancedSetting.ua`, який можна розібрати |
| `19005` | Недопустимий формат cookie | Передавайте `cookies` як екранований рядок JSON-масиву |
| `19039` | Профіль не знайдено | Перевірте `envId` / `uniqueId` і чи належить профіль вашій команді |
| `19063` | Досягнуто ліміту кількості профілів | Видаліть профілі або оновіть тариф |
| `19064` | Немає прав на цю групу | Попросіть адміністратора видати доступ до групи |
| `19065` | Немає прав на цей профіль | Попросіть адміністратора видати доступ до профілю |
| `19099` | Недостатньо доступних профілів, використання обмежено | Оновіть тариф |
| `19100` | Недопустимий ID платформи | Використовуйте `platformId` із `/system/platform/list` |
| `19101` | Недопустимий ID сайту | Використовуйте `siteId` із `/system/platform/list` |
| `19102` | URL користувацької платформи не може бути порожнім | Передавайте `platformUrl`, коли `platformId` дорівнює `9999` |
| `19103` | Недопустимий формат URL автозапуску | Передавайте коректні абсолютні URL у `afterStartupConfig` |
| `19104` | Недопустимий ID групи | Використовуйте групу, що існує у вашій команді |
| `19105` | Недопустимий ID мітки | Використовуйте мітки, що існують у вашій команді |
| `19106` | Недопустимий ID проксі | Використовуйте проксі, що існує у вашій команді, або опустіть `proxyId` |
| `19107` | Недопустима версія ядра браузера | Виберіть версію з `/env/advanced/ua/versions` |
| `19108` | Недопустима версія user agent | Виберіть версію з `/env/advanced/ua/versions` |
| `19109` | Версія user agent не збігається із самим user agent | Узгодьте `uaVersion` з `advancedSetting.ua` або передайте лише одне з них |
| `19110` | Недопустимий формат користувацького URL | Передайте коректний абсолютний URL |
| `19111` | Firefox підтримує лише Windows та macOS | Виберіть Windows або macOS чи перейдіть на Chrome |
| `19112` | Ключ шифрування не задано, увімкнути шифрування профілю неможливо | Налаштуйте ключ шифрування команди або передайте `isEncrypt=0` |
| `19141` | Не більше 100 символів, лише цифри, літери та пробіли | Скоротіть `accountInfo.otpSecret` і приберіть інші символи |
| `19142` | Профілі з наскрізним шифруванням змінити неможливо | Для зашифрованих профілів використовуйте клієнт MoreLogin |
| `19143` | Версія клієнта занадто стара для цього ядра | Оновіть десктопний клієнт MoreLogin |
| `19147` | Перевищено добовий ліміт створення | Оновіть тариф, щоб підняти ліміт |
| `19149` | Не вибрано тип кешу | Укажіть хоча б один клас кешу для очищення |
| `19159` | Операційна система не збігається з розширеними налаштуваннями | Під час оновлення ОС змінювати не можна; залиште `advancedSetting.os` як збережено |
| `19160` | Тип браузера не збігається з розширеними налаштуваннями | Під час оновлення браузер змінювати не можна; залиште `advancedSetting.vendor` як збережено |
| `19175` | Координати поза зоною обслуговування | Виберіть координати в межах підтримуваної зони |
| `19193` | Власник спільного доступу заборонив редагування цього профілю | Попросіть власника дозволити редагування |


### Хмарне сховище (`39xxx`)

| Код | Опис | Що робити |
|  --- | --- | --- |
| `39001` | Інформацію про хмарне сховище не знайдено | Перевірте, що хмарне сховище виділено команді |
| `39011` | Файл не знайдено | Перевірте ID файлу |
| `39014` | URL доступу до файлу порожній | Зареєструйте вивантаження заново |
| `39037` | Недопустимий параметр розширення файлу | Передайте підтримуване розширення |
| `39041` | Досягнуто квоти сховища | Видаліть файли, щоб звільнити місце |
| `39044` | Дублююча назва файлу | Перейменуйте файл |
| `39045` | Занадто багато непідтверджених передпідписаних вивантажень | Спершу завершіть або скасуйте непідтверджені вивантаження |
| `39046` | Файл не було вивантажено успішно | Вивантажте файл на передпідписаний URL до виклику complete |
| `39047` | Термін хмарного сховища сплив | Продовжте хмарне сховище |
| `39048` | Мітку хмарного сховища не знайдено | Використовуйте мітку з `/cloudstorage/tag/all` |
| `39049` | ID міток не можуть бути порожніми | Передайте хоча б одну мітку; порожній список відхиляється |
| `39050` | Назва файлу довша за 60 символів | Скоротіть назву |
| `39051` | Розмір файлу має бути більшим за 0 Б і меншим за 2 ГБ | Розділіть або стисніть файл |


### Проксі (`14xxx`) та гаманець (`20xxx`)

| Код | Опис | Що робити |
|  --- | --- | --- |
| `14003` | Не вдалося оновити проксі або проксі не існує | Перевірте ID проксі |
| `14017` | Проксі видалити неможливо | Проксі хмарної платформи з непротермінованим строком видалити неможливо; дочекайтеся спливання |
| `14023` | Тип проксі не існує | Використовуйте підтримуване значення сервісу |
| `14024` | Проксі не існує | Перевірте ID проксі |
| `14519` | Динамічні проксі змінити неможливо | Керуйте динамічними проксі за межами ендпоінтів проксі |
| `20018` | Не вдалося отримати ціну товару | Повторіть пізніше та повідомте `requestId` підтримці |
| `20029` | Рахунок гаманця недоступний | Перевірте гаманець команди |
| `20032` | Не вдалося запитати баланс | Повторіть пізніше та повідомте `requestId` підтримці |
| `20041` | Недостатньо коштів | Поповніть гаманець |


### Середовища виконання хмарного браузера (`40xxx`)

Повертаються ендпоінтами `/cloudbrowser/start`, `/cloudbrowser/stop` та `/cloudbrowser/connect`. Коди, що виникають після надсилання запиту на запуск, проявляються у `/cloudbrowser/page`, а не у відповіді на запуск.

| Код | Опис | Що робити |
|  --- | --- | --- |
| `40001` | Хмарний браузер уже запущений | Нічого робити не потрібно; підключіться до наявного запуску |
| `40002` | У поточному стані хмарний браузер зупинити неможливо | Перечитайте `/cloudbrowser/page` і повторіть |
| `40003` | Перевірка проксі не вдалася | Переконайтеся, що привʼязаний проксі досяжний |
| `40006` | Операція хмарного браузера не вдалася | Повторіть; якщо не вдалася архівація, дивіться `cloudBrowserArchiveStatus` |
| `40008` | Запущеного хмарного браузера не знайдено | Спершу запустіть його або перечитайте `/cloudbrowser/page` |
| `40009` | Неможливо підключитися до запуску іншого учасника | Попросіть цього учасника звільнити його |
| `40010` | Не вдалося підключитися до хмарного браузера | Повторіть; токен доступу до робочого столу не було випущено |
| `40015` | До профілю не привʼязано проксі | Спершу привʼяжіть проксі через `/env/setProxy/batch` |
| `40016` | Не вдалося надіслати запит на запуск | Повторіть |
| `40020` | Хмарний браузер зупиняється | Дочекайтеся завершення зупинки |
| `40021` | Хмарний браузер уже запускається | Не надсилайте повторно; опитуйте `/cloudbrowser/page` |
| `40023` | Профіль використовується | Спершу закрийте іншу сесію |
| `40024` | Хмарний браузер не запустився вчасно | Запустіть його знову |
| `40025` | Привʼязаний проксі більше не існує | Привʼяжіть проксі заново |
| `40026` | Привʼязаний проксі протермінований | Продовжте або замініть проксі |
| `40027` | Привʼязаний проксі ще виділяється | Повторіть після завершення виділення |
| `40028` | Локальні проксі не підтримуються | Використовуйте нелокальний проксі |
| `40029` | Цей тип проксі не підтримується | Використовуйте підтримуваний тип проксі |
| `40037` | Профілі з наскрізним шифруванням не можуть використовувати хмарний браузер | Використовуйте незашифрований профіль |


### Вебхуки (`41xxx`)

Повертаються ендпоінтами налаштування вебхуків, коли URL зворотного виклику відхилено.

| Код | Опис | Що робити |
|  --- | --- | --- |
| `41001` | URL зворотного виклику має бути коректною HTTPS-адресою | Передайте HTTPS-URL довжиною не більше 1024 символів, без даних користувача та фрагмента, з коректним портом, і переконайтеся, що всі адреси, у які він розв'язується, маршрутизуються в інтернеті |


### Автентифікація API (`35xxx`) та команди (`12xxx`)

| Код | Опис | Що робити |
|  --- | --- | --- |
| `12002` | Команда не існує | Команду учасника було видалено; зверніться до підтримки |
| `35002` | Автентифікація API не вдалася | Перевірте `client_id` (API ID) та `client_secret` (API-ключ) |
| `35005` | Запит не має прав на операцію | Учасника відключено або IP того, хто викликає, не проходить списки дозволених і заборонених IP Open API |


## Коди стану HTTP

| Статус | Опис |
|  --- | --- |
| `200` | Запит опрацьовано (бізнес-результат дивіться у полі `code`) |
| `401` | Не авторизовано — токен доступу недійсний або протермінований |
| `403` | Заборонено — недостатньо прав |
| `429` | Занадто багато запитів — перевищено ліміт частоти |
| `500` | Внутрішня помилка сервера — зверніться до підтримки |


Поточний шлюз застосунку позначає власну відмову за лімітом частоти бізнес-кодом `35000` і не виставляє HTTP `429` явно. Периферійний проксі або майбутня версія шлюзу все ж може повернути `429`, тому клієнтам варто обробляти обидва варіанти.

## Семантика повторів і відновлення

| Категорія збою | Повторювати? | Потрібна поведінка клієнта |
|  --- | --- | --- |
| Помилка валідації, прав, балансу або непідтримуваної можливості | Ні | Виправте запит, права, баланс або вибраний ресурс, і лише потім повторюйте |
| Обмеження частоти (`35000`) | Так, з умовами | Відступайте з дрижанням; перевіряйте `code` у тілі, навіть коли HTTP-статус дорівнює `200` |
| Тимчасовий збій сервера або Сервіса | Так, з умовами | Читання повторювати можна; для запису спершу запитайте стан ресурсу або задачі |
| Асинхронну операцію прийнято | Не надсилайте повторно відразу | Опитуйте задокументований ендпоінт стану до успіху, помилки або таймауту |
| Результат невідомий після мережевого таймауту | Спершу перевірте стан | Не повторюйте наосліп створення, купівлю, реєстрацію вивантаження або створення розкладу |


У публічному API зараз немає загального заголовка ключа ідемпотентності. Тому запити стану для конкретного ендпоінта — частина безпечного відновлення для запитів, що змінюють стан.

Для асинхронних операцій відповідь із `code: 0` може означати «прийнято», а не «завершено». Орієнтуйтеся на документацію операції: її поле стану та кінцеві стани.

Повний перелік операцій див. у [матриці повторів і завершення ендпоінтів](/uk/api-reference/getting-started/endpoint-behavior), а порядок опитування та кінцеві стани — в [Асинхронних операціях](/uk/api-reference/getting-started/async-operations).

> **Порада**: звертаючись до підтримки, завжди вказуйте `requestId` з відповіді — це прискорить розбір.