Ошибки SDK
Коды FingprintAgentError, когда они возникают и как их исправить.
Все ожидаемые ошибки @fingerru/agent — экземпляры FingprintAgentError. По полю code определите причину и решите, что показать пользователю или записать в лог.
Обработайте ошибку
Проверьте класс ошибки и прочитайте code:
import { FingprintAgentError, start } from '@fingerru/agent'
const agent = start({ apiKey: 'pk_live_example' })
try {
const visitor = await agent.get()
console.log(visitor.user)
} catch (error) {
if (error instanceof FingprintAgentError) {
console.error(error.code, error.message, error.status)
} else {
throw error
}
}У FingprintAgentError есть поля:
| Поле | Описание |
|---|---|
code | Код ошибки из таблиц ниже. Используйте его в условиях вместо текста message. |
message | Описание ошибки на русском языке. Текст может меняться, поэтому не сравнивайте его в коде. |
status | HTTP-статус ответа. Есть только у API_HTTP_ERROR. |
cause | Исходная ошибка, если она есть: например, ошибка fetch или разбора JSON. |
name | Всегда 'FingprintAgentError'. |
При подключении через CDN класс доступен как FingprintAgent.FingprintAgentError.
В @fingerru/react и @fingerru/vue ошибка запроса попадает в поле error, которое возвращает useVisitorData.
Ошибки настройки
Эти ошибки start() выбрасывает сразу при создании агента. Исправьте параметры в коде — повторный вызов с теми же значениями снова завершится ошибкой.
| Код | Когда возникает | Что сделать |
|---|---|---|
API_KEY_MISSING | apiKey не передан или состоит из пробелов. | Передайте публичный API-ключ проекта. |
INVALID_ENDPOINT | endpoint не является HTTP(S) origin: содержит путь, query, hash, логин или пароль, или это не URL. | Оставьте в endpoint только протокол и домен, например https://metrics.example.com. |
INVALID_TIMEOUT | loadTimeout не является положительным конечным числом. | Укажите время в миллисекундах больше 0. |
INVALID_CACHE_CONFIG | В cache неизвестное storage, duration не больше 0 или больше 43200 секунд или пустой keyPrefix. | Проверьте поля cache по описанию параметра. |
INVALID_TIMEOUT также возникает в get(), если передан неверный timeout. В этом случае get() возвращает отклонённый Promise.
Ошибки загрузки скрипта
SDK загружает скрипт сбора данных при первом вызове get() или collect(). Если загрузка не удалась, следующий вызов попробует загрузить скрипт снова.
| Код | Когда возникает | Что сделать |
|---|---|---|
RUNTIME_LOAD_FAILED | Браузер не смог загрузить скрипт или SDK вызван вне браузера, например при серверном рендеринге. | Проверьте сетевой запрос к скрипту во вкладке Network и блокировщики. Вызывайте SDK только в клиентском коде. |
RUNTIME_LOAD_TIMEOUT | Скрипт не загрузился за loadTimeout. | Проверьте доступность адреса скрипта. При медленной сети увеличьте loadTimeout. |
RUNTIME_NOT_FOUND | Скрипт загрузился, но не зарегистрировал глобальный объект. | Если используете endpoint, убедитесь, что прокси по пути /js/agent.min.js отдаёт скрипт Fingprint без изменений. |
RUNTIME_INVALID | В загруженном скрипте нет функции сбора данных. | Проверьте, что по адресу скрипта отдаётся скрипт Fingprint. |
PROTOCOL_VERSION_MISMATCH | Версия скрипта сбора данных не совместима с версией SDK. | Обновите @fingerru/agent. Если на странице уже подключён другой скрипт Fingprint, оставьте одну версию. |
RUNTIME_COLLECT_FAILED | Скрипт загрузился, но сбор данных завершился ошибкой. | Посмотрите исходную ошибку в cause. Повторите вызов. |
Ошибки запроса к API
Эти ошибки возвращает только get(): collect() к API не обращается.
| Код | Когда возникает | Что сделать |
|---|---|---|
API_PAYLOAD_ERROR | SDK не смог подготовить тело запроса из собранных данных. | Посмотрите исходную ошибку в cause. |
API_NETWORK_ERROR | Запрос не дошёл до API: нет сети, адрес недоступен, запрос заблокирован браузером или CORS. | Проверьте запрос к /api/visit во вкладке Network. Если используете endpoint, проверьте, что прокси принимает POST. |
API_TIMEOUT | API не ответил за timeout из get(). | Повторите запрос. При медленной сети увеличьте timeout. |
API_HTTP_ERROR | API ответил статусом вне диапазона 200–299. Статус доступен в error.status. | Проверьте статус и ключ: передан ли публичный ключ нужного проекта и активен ли он на странице API-ключи в кабинете. |
API_INVALID_RESPONSE | API вернул не JSON или JSON без непустой строки user. | Если используете endpoint, проверьте, что прокси передаёт ответ API без изменений. |
Если ошибка возникла при загрузке скрипта или запросе к API, результат не попадает в кеш. Следующий вызов get() выполнит запрос заново.