Ошибки API меток

Если создание или поиск метки вернули NULL, прочитайте GetLastError() у серверного или клиентского API. Если не сработал метод полученной метки, например Apply(), спрашивайте ошибку у этой метки. У FlushMarkerWrites ошибка возвращается через выходной аргумент. Сохраните строку сразу после отказа: следующий вызов может её изменить.

У карты два вида ошибок. Строка с # уже является ключом перевода: для показа игроку передайте её в Widget.TranslateString на клиенте. Строка без # является служебным кодом API, а не ключом из таблицы переводов. Для неё выберите действие или свой перевод. В условиях сравнивайте исходную строку, не переведённый текст. Ниже перечислены ошибки личных, серверных и временных клиентских меток; у интеграций групп свои ответы.

У временной метки SetPositionDynamic() требует первого Apply() и отсутствия подготовленных правок, иначе вернёт LXWM_NOT_PUBLISHED или LXWM_PENDING_CHANGES. При проверке временной записи используются общие ключи #LXWM_ServerMarkerInvalid... и #LXWM_ServerMarkerIDUsed, хотя запись не отправляется на сервер. Ошибки личного хранилища и записи серверных файлов к ней не относятся. После отключения временная метка удалена: получить её по старому ID при новом подключении нельзя.

Служебные коды

Значение	Что произошло и как поступить
`LXWM_NOT_READY`	Миссия или клиентские данные ещё не готовы, либо объект остался от законченной миссии. После переподключения получите метку заново по ID.
`LXWM_MARKER_NOT_FOUND`	Объект больше не существует или запись с таким ID недоступна в этом источнике. Отсутствие записи на клиенте не доказывает, что её удалили с сервера.
`LXWM_READ_ONLY`	У объекта нет права прямой записи. Серверная метка на клиенте только для чтения; администратор может использовать штатный редактор.
`LXWM_NOT_PUBLISHED`	Для этой операции нужна опубликованная метка. Например, нельзя перемещать серверный черновик через `SetPositionDynamic` до первого `Apply()`.
`LXWM_PENDING_CHANGES`	У объекта есть неподтверждённые правки или он ещё черновик. Для опубликованного объекта выберите: принять правки через `Apply()` или отказаться от них через `Refresh()`.
`LXWM_INVALID_ARGUMENT`	Неверный аргумент метода, например цвет, скорость или позиция копии. Исправьте конкретное поле; повторный `Apply()` с теми же данными не поможет.
`LXWM_STORAGE_UNAVAILABLE`	Личное хранилище клиента пока недоступно для записи. Проверьте `CanWritePersonalMarkers()`.
`LXWM_INVALID_MARKER`	Личная метка не прошла проверку. Проверьте название, иконку, координаты, цвет и параметры зоны.
`LXWM_MARKER_ID_USED`	ID нового личного черновика уже занят. Создайте новый черновик, не удаляйте существующую запись.
`LXWM_ZONE_FORBIDDEN`	При сохранении личной метки отклонена зона. Проверьте `CanUsePersonalZones()`; при необходимости предложите игроку обычную точку.
`LXWM_SAVE_FAILED`	Не удалось сохранить изменение личной базы. Проверьте клиентский профиль и права процесса игры на запись.
`LXWM_MARKER_UNAVAILABLE`	Клиентский объект нельзя использовать для действия в меню: например, он недействителен, ещё не опубликован или имеет неподтверждённые правки.
`LXWM_ACTION_UNAVAILABLE`	Объект есть, но действие не сработало. Проверьте, открыта ли карта, доступна ли панель метки и разрешено ли выбранное действие.

Ключи перевода

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

Ключ	Что проверить
`#LXWM_ServerMarkerInvalidID`	ID: от 1 до 64 латинских букв, цифр, дефисов и подчёркиваний. Зарезервированные имена Windows не подходят.
`#LXWM_ServerMarkerIDUsed`	ID уже занят, в том числе если отличается только регистр букв. В переводе есть `%1`: подставьте ID, который пытались назначить.
`#LXWM_ServerMarkerNotFound`	Обработчик не нашёл запись для изменения, удаления или движения. Проверьте актуальный ID.
`#LXWM_ServerMarkerInvalidName`	Название пустое или длиннее 256 символов по `LengthUtf8()`.
`#LXWM_ServerMarkerInvalidWorld`	Не задан игровой мир метки. Не подставляйте вместо него адрес сервера.
`#LXWM_ServerMarkerInvalidIcon`	Проверьте, каким методом задана иконка. Для `SetMarkerIconID()` нужен ID Lucide, например `map-pin`. Для `SetMarkerIconPath()` нужен путь к файлу `.paa` или `.edds` внутри аддона (до 255 байт), без буквы диска, URL или перехода `..`. После отказа исправьте путь или передайте пустую строку и повторите `Apply()`.
`#LXWM_ServerMarkerInvalidPosition`	Одна из трёх координат некорректна: например, не является числом или по модулю больше 10000000.
`#LXWM_ServerMarkerInvalidColor`	В цвете метки не три компонента RGB или значение вне диапазона 0–255.
`#LXWM_ServerMarkerInvalidZone`	Неверные настройки зоны: форма, размеры или цвета. Проверяются и размеры, не используемые текущей формой.
`#LXWM_ServerMarkerInvalidVisibilityRadius`	Радиус показа должен быть больше 0 и не больше 10000000 м. Это не радиус нарисованной зоны.
`#LXWM_ServerMarkerInvalidAudience`	В списке получателей есть некорректный SteamID64. Передавайте каждый ID отдельной строкой массива.
`#LXWM_ServerMarkerInvalidAnimations`	Неверный набор эффектов: проверьте формат ID, число записей (до 16) и скорости (от 0.05 до 10).
`#LXWM_ServerMarkerInvalidRequest`	Обработчик не принял данные запроса. Не путайте этот отказ с потерей соединения.
`#LXWM_ServerMarkerWriteFailed`	Сервер не смог безопасно изменить файлы. Проверьте серверный лог и права на запись, переименование и удаление в профиле.

Ответы штатного редактора: #LXWM_ServerMarkerNotAdmin означает, что сервер не подтвердил права; #LXWM_ServerMarkerCopyLimit ограничивает одну операцию размещения 1–128 копиями; #LXWM_ServerMarkerTimeout означает, что клиент не дождался ответа. При таймауте операция уже могла завершиться. Проверьте актуальное состояние перед повтором. Это ответы интерфейса, не результат GetLastError() сразу после OpenEditor(). Ошибки телепорта и интеграций групп к обычной метке не относятся.

Если API вернул #LXWM_ServerMarkerWriteFailed, а причина неясна, в серверном логе может быть более точная диагностика. Эти ключи описывают состояние файлов; не ожидайте их напрямую от Apply():

Ключ в диагностике хранилища	Что означает
`#LXWM_ServerMarkerFileOccupied`	Имя файла уже занято другой записью. Не перезаписывайте её вручную.
`#LXWM_ServerMarkerInvalidJSON`	Не удалось прочитать JSON. Проверьте доступ, синтаксис и типы полей; ошибка чтения сама по себе не означает, что метки нет.
`#LXWM_ServerMarkerInvalidStorageKey`	Некорректный внутренний ключ хранилища. Это не публичный ID, который задаётся через `SetMarkerID()`.
`#LXWM_ServerMarkerDuplicateFileID`	Один публичный ID встретился в нескольких файлах.
`#LXWM_ServerMarkerDuplicateStorageKey`	Обнаружены файлы с одинаковым внутренним ключом и одной ревизией.
`#LXWM_ServerMarkerIncompleteBatch`	Нет подтверждения завершения пакетного копирования. Не удаляйте файлы для восстановления до проверки резервной копии.

Пример: показать причину отказа

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

string DescribeMarkerFailure(string FailureCode, string RequestedMarkerID)
{
	if (FailureCode == "#LXWM_ServerMarkerIDUsed")
	{
		return string.Format(Widget.TranslateString(FailureCode), RequestedMarkerID);
	}
	if (FailureCode == "LXWM_MARKER_NOT_FOUND")
	{
		return Widget.TranslateString("#LXWM_ServerMarkerNotFound");
	}
	if (FailureCode.IndexOf("#") == 0)
	{
		return Widget.TranslateString(FailureCode);
	}
	return FailureCode;
}

Не все действия работают с кодами ошибок. Например, FocusPlayer() и CloseMap() сообщают об отказе через false, но не записывают причину в GetLastError(). После таких вызовов там может оставаться ошибка от предыдущего поиска метки.