API

1 Назначение

Бэкенд DataForge публикует публичный API для внешних интеграций и AI-агентов.

Публичный API имеет две версии, каждая со своим базовым путём:

Группа эндпоинтов	Базовый путь	Состав	Аудитория
Публичный DF API v1	/df-api/v1	Только чтение: проекты, версии, содержимое РПИ (показатели, измерения, факты), витрины, подключения, группы измерений, таблицы фактов, связи, сводный экспорт РПИ	Внешние интеграции, AI-агенты
Публичный DF API v2	/df-api/v2	Чтение и запись: полноценный CRUD для проектов, версий, содержимого РПИ, групп измерений, таблиц фактов и связей; витрины и подключения на чтение; экспорт/импорт версий и управление Git-подключениями; идемпотентная запись и генерация SQL для показателей	Внешние интеграции, CI/CD, AI-агенты

Базовые принципы, применяемые ко всем вызовам публичного API:

Принцип	Описание
Версионирование в URL	Публичный API версионируется через путь URL (/v1/). Внутри одной мажорной версии контракт расширяется аддитивно — новые опциональные поля могут появляться, существующие не удаляются и не переименовываются
Версионирование данных	Каждый эндпоинт, работающий с РПИ, таблицами фактов, витринами или подключениями, привязан к версии проекта
Доступ к данным	v1 (/df-api/v1) доступна только на чтение. df-api/v2 добавляет полноценный CRUD на чтение и запись для проектов, версий, содержимого РПИ и модели данных (страница Публичный API v2). Ни один эндпоинт публичного API не выполняет запросов данных в подключённых СУБД и не раскрывает учётных данных СУБД
Троттлинг	Обе версии ограничены одинаково: 100 запросов за 60 секунд на один API-ключ (раздел 2.4)
Контроль лицензии	Весь публичный API доступен только при действующей лицензии вызывающей компании
Аудит	Каждый запрос публичного API — его аутентификация и исход, успешный или неуспешный — записывается в журнал аудита

Полные базовые URL развёрнутой системы: https://<host>/df-api/v1 и https://<host>/df-api/v2. В on-premises-инсталляциях используется хост, заданный шаблоном развёртывания; nginx терминирует TLS перед бэкендом.

2 Аутентификация и авторизация

2.1 API-ключ

Публичный API использует долгоживущие API-ключи, создаваемые в карточке пользователя (см. страницу Ключи API). У каждого пользователя в любой момент времени активен не более одного ключа; генерация нового замещает предыдущий. Plaintext ключа показывается оператору один раз и не сохраняется — хранится только его bcrypt-хэш.

ApiKeyGuard (применён ко всем эндпоинтам v1 и v2) выполняет следующие проверки в указанном порядке на каждом запросе:

1. Наличие API-ключа. Если заголовок X-Api-Key отсутствует → 401 API_KEY.KEY_MISSING.
2. Валидность API-ключа. Переданный ключ bcrypt-сравнивается с каждым сохранённым хэшем; при несовпадении → 401 API_KEY.INVALID_KEY.
3. Статус пользователя. Если найденный пользователь не в статусе ENABLED → 403 API_KEY.ACCOUNT_LOCKED.
4. IP-фильтрация. IP клиента, определённый по доверенному для режима развёртывания источнику, проверяется по белому и чёрному спискам компании. Заблокировано → 403 API_KEY.IP_BLOCKED.
5. Наличие компании. Если у пользователя нет компании → 403 API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE.
6. Действующая лицензия. Проверяется лицензия компании. При сбое → 403 API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE. См. раздел 9.5.
7. Аудит. Запись об успехе или неудаче записывается в журнал аудита (тип API_ACCESS, действие API_ACCESS_SUCCESSFUL / API_ACCESS_FAILED).

2.2 Роли и доступ к проектам

Большинство эндпоинтов публичного API доступны только на чтение и собственной проверки роли не выполняют. Эндпоинты записи df-api/v2 проверяют доступ на запись в разрезе проекта (см. ниже и раздел 1 страницы Операции записи в публичном API v2). Статус пользователя по-прежнему важен для аутентификации: владелец ключа должен быть в статусе ENABLED.

Наследование доступа к проектам. API-ключ наследует интерактивный (UI) доступ к проектам владельца ключа. В результате:

• Эндпоинты, привязанные к конкретному проекту (/projects/{id}/versions, все эндпоинты в разрезе версии, а также эндпоинты модели данных и витрин), возвращают 404 Not Found, если у владельца ключа нет доступа к этому проекту — факт существования проекта не раскрывается вызывающим без доступа.
• Эндпоинты списка проектов (GET /projects в v1 и v2) фильтруются по проектам, доступным владельцу ключа; недоступные проекты исключаются из страницы и из общего количества.

Это применяется единообразно в v1 и v2.

df-api/v2 — полноценный CRUD API на чтение и запись (страница Публичный API v2). Запись в РПИ и модель данных требует, чтобы владелец ключа разрешался в эффективную роль в проекте «разработчик или выше»; эндпоинты управления доступом (раздел 3 страницы Операции записи в публичном API v2) дополнительно ограничены владельцем проекта или администратором компании/суперадминистратором. Экспорт версии и сухие прогоны импорта требуют роли «аналитик или выше», импорт версии — «разработчик или выше», управление Git-подключениями — COMPANY_ADMIN (раздел 4–5 страницы Операции записи в публичном API v2). v1 остаётся только для чтения.

2.3 IP-фильтрация

IP-фильтрация применяется на каждом запросе публичного API сразу после проверки ключа.

Компания может включить белый список IP, чёрный список IP или оба. Каждый список поддерживает либо точные IPv4-адреса, либо CIDR-диапазоны. При включённом белом списке отклоняются запросы с IP, не входящих в список; при включённом чёрном — запросы с IP, входящих в список. Неуспешные проверки IP пишутся в журнал аудита как API_ACCESS / API_ACCESS_FAILED.

2.4 Throttling

Обе версии публичного API — /df-api/v1 и /df-api/v2 — применяют один и тот же троттлинг на уровне API-ключа: не более 100 запросов в 60 секунд на ключ (окно скользящее, счётчик ведётся по значению X-Api-Key). Каждый ответ публичного API содержит заголовки:

Заголовок	Описание
X-RateLimit-Limit	Максимальное число запросов в окне
X-RateLimit-Remaining	Оставшееся число запросов в текущем окне
X-RateLimit-Reset	Unix timestamp момента сброса счётчика

При превышении лимита возвращается 429 Too Many Requests с ключом DF_API.RATE_LIMIT_EXCEEDED в originalMessage; в df-api/v2 ответ дополнительно несёт code: "rate_limit_exceeded" (раздел 4 страницы Публичный API v2). Отклонённый запрос записывается в журнал аудита как API_ACCESS_FAILED (раздел 7).

Счётчики ведутся в общем хранилище (Redis) для всех экземпляров бэкенда, поэтому лимит применяется к ключу целиком, а не к каждому экземпляру отдельно: параллельная серия запросов, распределённая между несколькими экземплярами, ограничивается так же, как последовательная. Если общее хранилище недоступно, подсчёт временно ведётся в пределах экземпляра — доступность API от этого не страдает, снижается только точность лимита.

2.5 Контроль лицензии

Лицензия проверяется после аутентификации и IP-фильтрации. Все эндпоинты публичного API отклоняются при отсутствии действующей лицензии. Возвращаемая ошибка одинакова независимо от конкретной причины: 403 Forbidden с кодом API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE. См. раздел 5 для условий и порядка восстановления.

2.6 Транспортная безопасность

Все эндпоинты публичного API должны обслуживаться по HTTPS с TLS 1.2 или выше. Шаблон on-premises-развёртывания поднимает nginx с терминированием TLS перед бэкендом; сам бэкенд слушает обычный HTTP внутри доверенной сети.

API-ключи хранятся как bcrypt-хэши и никогда не возвращаются в ответах. Полный список полей, не возвращаемых ответами, см. в разделе 9.6.

3 Общие соглашения по запросам и ответам

3.1 Формат запроса

Свойство	Значение
Content-Type	application/json для JSON-тел
Charset	UTF-8
Заголовок аутентификации	X-Api-Key: <key>
Язык	Опциональный Accept-Language; query-параметр language имеет приоритет

3.2 Пагинация

List-эндпоинты используют единую форму пагинации. Параметры query:

Параметр	Тип	По умолчанию	Описание
page	integer	1	Номер страницы (нумерация с 1)
pageSize	integer	20	Максимум 100. Списки витрин, подключений и Git-подключений (v1 и v2), а также групп измерений, таблиц фактов и связей в v1 отклоняют большее значение с 400 DF_API.PAGE_SIZE_EXCEEDED; списки проектов, версий, содержимого РПИ, групп измерений, таблиц фактов и связей в v2 молча ограничивают его до 100; эндпоинты проектов, версий и содержимого РПИ в df-api/v1 не ограничивают
Параметры фильтра	разные	—	Конкретные фильтры на эндпоинт (описаны inline)

Конверт ответа (большинство list-эндпоинтов DF API):

{
  "data_marts": [ /* items */ ],
  "pagination": { "page": 1, "pageSize": 20, "total": 45, "total_pages": 3 }
}

Конверт ответа (list-эндпоинты содержимого РПИ — …/measures, …/dimensions, …/facts в df-api/v1, списки проектов и версий, а также все list-эндпоинты df-api/v2):

{
  "measures": [ /* items */ ],
  "pagination": { "total": 42, "page": 1, "pageSize": 20, "totalPages": 3 }
}

3.3 Локализация

Ответы публичного API учитывают query-параметр language (ru или en). Локализуются только описательные текстовые значения (метки статусов, типов, выпадающих списков); ключи JSON всегда на английском.

3.4 Временные метки

Все временные метки в ответах используют формат ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).

3.5 Форматы вывода

Эндпоинты содержимого РПИ (…/measures, …/dimensions, …/facts), списки проектов и версий, а также эндпоинты модели данных и сводного экспорта РПИ поддерживают ?format=json (по умолчанию) и ?format=xlsx. При xlsx тело ответа имеет вид { "downloadUrl": "<подписанная ссылка S3, действует 15 минут>" }. Эндпоинты витрин и подключений возвращают только JSON. Некорректное значение format возвращает 400 Bad Request с кодом DF_API.INVALID_FORMAT.

3.6 Объект источника

Все поля, указывающие на физическое расположение данных в подключённой базе, используют один и тот же объект:

{
  "connection": "Production PostgreSQL",
  "db": "analytics_db",
  "schema": "public",
  "table": "fact_sales",
  "column": "amount"
}

Поле	Тип	Обязательное	Описание
connection	string	да	Название подключения, которому принадлежит источник
db	string	да	База данных этого подключения
schema	string | null	нет	Схема базы данных
table	string	да	Название таблицы
column	string | null	нет	Название колонки; null, если ссылка идёт на таблицу целиком

Как кодируется отсутствие. В ответах используются два разных «пустых» значения, и на запись принимаются оба:

Объект	Отсутствие схемы	Отсутствие колонки
объекты источника (connected_source, primary_key, foreign_key)	"" — формат, общий с выгрузкой и импортом РПИ	null
описания подключений и таблиц (GET /connections, tables[].schema)	null	—

На запись schema и column принимают пустую строку, null и отсутствие поля — все три означают «не передано», поэтому объект, полученный из любого эндпоинта, можно отправить обратно без правок. Обязательны только db и table.

Слово schema в четырёх ролях. Три из них — имя схемы, четвёртая — имя ключа-контейнера:

Где	Тип	Значение
GET /connections → schema	string | null	Схема, выбранная у подключения. Только для PostgreSQL; null для MS SQL и ClickHouse
GET /connections/{id}/schema → schema	объект	Контейнер: { connection, tables[] }. В деталях подключения тот же объект называется db_schema
…tables[].schema	string | null	Схема, в которой лежит таблица. null для ClickHouse, где схем нет
schema в объекте источника	string	Где лежит источник. "" для MS SQL (схема внутри table) и ClickHouse

Эту форму используют connected_source (измерения, факты), primary_key (группы измерений, детали таблицы фактов, связи) и foreign_key (детали таблицы фактов, связи). Она же применяется в выгрузке и загрузке РПИ в самом продукте, поэтому объект, полученный из API, можно без преобразований положить в файл импорта РПИ.

Поведение schema зависит от диалекта:

• PostgreSQL — схема принадлежит подключению, поэтому поле повторяет схему самого подключения;
• MS SQL Server — схема свёрнута в table (dbo.orders), а schema пустая;
• ClickHouse — схем не существует, schema пустая.

connection — единственное поле, однозначно определяющее источник. В одной версии проекта может быть несколько подключений к одной и той же базе, различающихся схемой, учётными данными или хостом: по db их не различить, по названию подключения — можно (названия уникальны в пределах версии).

Доступность. connection возвращают только эндпоинты v2 (страница Публичный API v2), и они же принимают его на запись. В ответах v1 (разделы 1–2 страницы Публичный API v1) тот же объект приходит без этого поля.

Правила по диалектам, описанные выше, действуют на всех эндпоинтах v2. В v1 их применяют только эндпоинты РПИ (/rmd/*); эндпоинты справочников, таблиц фактов и связей v1 отдают схему, сохранённую в строке, с откатом к схеме подключения.

3.7 Как описаны эндпоинты

Каждый эндпоинт на страницах Публичный API v1, Публичный API v2 и Операции записи в публичном API v2 описан одними и теми же четырьмя блоками в одном и том же порядке:

Блок	Содержимое
Запрос	Метод и полный путь, затем одна таблица всех входных данных эндпоинта: параметры пути, параметры query, заголовки и поля тела. Колонки: Параметр (имя; поля тела записываются путём через точку, например options.include_rmd), Где (путь, query, заголовок, тело), Тип, Обяз. (да / нет), Описание (значения по умолчанию, допустимые значения, ограничения)
Детали	Поведение, которое клиенту нужно знать и которое не умещается в таблицы: правила доступа, побочные эффекты, идемпотентность, особенности диалектов. Опускается, если добавить нечего
Ответ	Статус успеха, характерное тело JSON и таблица полей (Поле, Тип, Описание). Пути полей записываются через точку; [] обозначает элемент массива (measures[].id)
Ошибки	Коды, которые этот эндпоинт возвращает помимо общих. Коды, общие для всех эндпоинтов (аутентификация, лицензия, лимит частоты, разрешение проекта и версии), перечислены один раз в разделе 4 и далее называются «общими ошибками»

Два входных параметра в таблицах не повторяются: заголовок X-Api-Key, обязательный для каждого эндпоинта (раздел 2.1), и необязательный заголовок Accept-Language, который каждый эндпоинт учитывает как запасной вариант параметра language (раздел 3.3). Заголовок Idempotency-Key указан только у тех эндпоинтов, которые его учитывают. Идентификаторы в путях — положительные целые числа (раздел 4); в телах и ответах v2 они передаются строками.

4 Обработка ошибок

Ошибки v1 возвращаются в едином формате из четырёх полей:

{
  "message": "string",
  "originalMessage": "string",
  "statusCode": 404,
  "error": "string"
}

Поле	Описание
message	Локализованное человекочитаемое сообщение (учитывает ?language / Accept-Language)
originalMessage	Исходный ключ ошибки (например, DF_API.PROJECT_NOT_FOUND); стабильный идентификатор для клиентов
statusCode	HTTP-код статуса
error	Имя класса исключения

df-api/v2 использует собственный фильтр и расширяет этот конверт двумя машиночитаемыми полями — code и details. Формат описан в разделе 4 страницы Публичный API v2 и одинаков для всех эндпоинтов v2, включая ошибки, поднятые guard'ами (неверный ключ, IP, лицензия, превышение лимита).

Стандартные HTTP-коды:

Код	Значение
200	Успех
201	Создано — POST создания в v2, а также generate-sql в v1 (раздел 2.4 страницы Публичный API v1)
204	Нет содержимого — DELETE в v2
207	Multi-Status — массовая операция v2 (…/bulk) применена частично (раздел 1 страницы Операции записи в публичном API v2)
400	Bad Request — нарушение валидации, параметра или бизнес-правила
401	Unauthorized — отсутствует или некорректен API-ключ
403	Forbidden — IP заблокирован, учётка заблокирована, лицензия невалидна
404	Not Found — ресурс не существует или недоступен вызывающему
409	Conflict — дублирующее имя, элемент со ссылками или выполняющийся ключ идемпотентности (запись в v2)
422	Unprocessable Entity — семантическая ошибка валидации записи (формула/ссылка/зависимость, конфликт глобальной версии) (запись в v2)
429	Too Many Requests — превышен лимит запросов на API-ключ (все группы)
500	Internal Server Error

Идентификаторы ресурсов. Идентификаторы в пути (project_id, version_id, data_mart_id, connection_id и т. д.) и идентификаторы в телах запросов записи v2 — положительные целые числа в диапазоне до 2147483647 (int4). Числовое значение вне этого диапазона не может соответствовать ни одной записи и отвечается 404 с кодом «не найдено» адресуемого ресурса (DF_API.PROJECT_NOT_FOUND, DF_API.VERSION_NOT_FOUND, DF_API.DATA_MART_NOT_FOUND и т. д.) — точно так же, как несуществующий ресурс. Правило действует единообразно в v1 и v2.

Ошибки, общие для всех эндпоинтов. Следующие коды может вернуть любой эндпоинт публичного API; блоки «Ошибки» у отдельных эндпоинтов на страницах эндпоинтов их не повторяют.

HTTP	df-api/v1	df-api/v2 (originalMessage / code)	Условие
401	API_KEY.KEY_MISSING	DF_API.INVALID_API_KEY / invalid_api_key	Заголовок X-Api-Key отсутствует
401	API_KEY.INVALID_KEY	DF_API.INVALID_API_KEY / invalid_api_key	Ключ не совпал ни с одним сохранённым
403	API_KEY.ACCOUNT_LOCKED	DF_API.ACCOUNT_LOCKED / account_locked	Владелец ключа не в статусе ENABLED
403	API_KEY.IP_BLOCKED	DF_API.IP_NOT_ALLOWED / ip_not_allowed	IP клиента в чёрном списке или вне белого
403	API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE	DF_API.LICENSE_INVALID / license_invalid	У компании нет действующей лицензии (раздел 5)
429	DF_API.RATE_LIMIT_EXCEEDED	DF_API.RATE_LIMIT_EXCEEDED / rate_limit_exceeded	Исчерпана квота 100 запросов / 60 с на ключ (раздел 2.4)
400	DF_API.INVALID_PARAMETER	DF_API.INVALID_PARAMETER / invalid_parameter	Идентификатор в пути не является числом (только df-api)
404	DF_API.PROJECT_NOT_FOUND	DF_API.PROJECT_NOT_FOUND / project_not_found	Проект не существует или недоступен владельцу ключа
404	DF_API.VERSION_NOT_FOUND	DF_API.VERSION_NOT_FOUND / version_not_found	Версия не существует в проекте
400	DF_API.INVALID_FORMAT	DF_API.INVALID_FORMAT / invalid_format	format вне значений, которые принимает эндпоинт (раздел 3.5)
500	—	DF_API.INTERNAL_ERROR / internal_error	Неожидаемый сбой на сервере; внутренние детали не возвращаются

Полный каталог кодов — в разделе 9.11.

5 Проверка лицензии

Проверка лицензии — единственная точка контроля, решающая, разрешён ли публичный API-доступ компании. Она выполняется после аутентификации и IP-фильтрации.

Проверка отвечает 403 Forbidden при выполнении любого из условий для компании вызывающего:

Условие	Описание
У компании отсутствует запись лицензии	license равен null
Тип лицензии — NO_LICENSE	Заглушка, назначаемая по умолчанию до активации
Статус лицензии — INVALID	Истекла, не была валидирована или отозвана
Статус лицензии — SUSPENDED	Превышены лимиты лицензии (пользователи, проекты, версии)

Публичный API мапит все эти условия в одну ошибку, чтобы не раскрывать детали состояния лицензии:

HTTP	Код	Тело
403	API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE	{ "message": "API is not available without a valid license", "originalMessage": "API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE", "statusCode": 403, "error": "ForbiddenException" }

Неуспешная попытка доступа из-за невалидной лицензии записывается в журнал аудита (тип API_ACCESS, действие API_ACCESS_FAILED).

Чтобы восстановить доступ к API, администратор компании (или, в облачных инсталляциях, Super Admin) должен загрузить действующую лицензию через экран управления лицензиями и удостовериться, что компания не выходит за лимиты по пользователям, проектам и версиям соответствующего тарифа.

6 Ограничения безопасности

Следующие поля никогда не должны появляться в ответах публичного API:

Поле	Причина
password	Учётные данные подключения к СУБД и пароль пользователя
ssl_certificate, caCertificateFileName, clientCertificateFileName	Сертификатный материал
ssl_key, clientPrivateKeyFileName	Закрытые ключи
token, apiKey, key	JWT, refresh-токены, API-ключи, сессионные токены
connection_string	Может содержать встроенные учётные данные
signature (сущность License)	HMAC лицензии; никогда не возвращается клиенту
Любые пользовательские поля учётных данных	Чувствительные значения, заданные пользователем

Идентификаторы, намеренно раскрываемые как несекретный контекст:

Поле	Причина допуска
username (подключение СУБД)	Имя пользователя СУБД — необходимо для построения SQL, не является секретом
host, port, database, schema	Сетевые координаты, известные любому, у кого есть доступ на чтение модели данных

Шифрование данных в покое:

Поле	Хранилище	Шифр
API-ключ	база данных	bcrypt
Пароль удалённой СУБД	база данных	AES (ключ управляется приложением)
SSL-файлы удалённой СУБД	объектное хранилище (MinIO/S3)	server-side encryption
Подпись лицензии	база данных	HMAC; проверяется, не возвращается

7 Журналирование аудита

Каждый запрос публичного API (v1 и v2) записывается после выполнения обработчика, поэтому исход известен. Каждая запись содержит тип, действие, актора, IP-источник, целевой объект и свободное поле what:

Событие	Тип	Действие	Триггер
Успешный запрос к API	API_ACCESS	API_ACCESS_SUCCESSFUL	Запрос аутентифицирован и его обработчик завершился успешно
Неуспешный запрос к API	API_ACCESS	API_ACCESS_FAILED	Аутентификация отклонена (ключ отсутствует/невалиден, учётка заблокирована, IP заблокирован, лицензия невалидна) или аутентифицированный запрос вернул ошибку — неуспешное чтение, неуспешная запись df-api/v2 или отклонение по лимиту 429

Кроме того, каждая успешная операция записи df-api/v2 (создание/обновление/удаление содержимого РПИ, модели данных, доступа к проекту и Git-подключений, а также импорт версии) фиксируется в аудите со снимками before/after затронутой сущности: замена версии импортом записывает в before метку и счётчики содержимого затёртой версии. Операции переноса версий через публичный API не дублируются в журнале экспорта/импорта, видимом в интерфейсе, — их единственный след — записи API_ACCESS.

Поля журнала аудита:

Поле	Значение
type	Категория события (API_ACCESS)
action	Конкретное действие в категории
who	Email актора (владелец API-ключа)
from_where	IP клиента из доверенного источника, либо UNKNOWN
where	Имя компании
what	Версия API (DfApi v1 или DfApi v2; отклонение по лимиту 429 всегда записывается как DfApi v2 — общий для обеих версий троттлер знает только это имя); для неуспешного запроса добавляется причина отказа или ошибки (например, … — Invalid API key), а для записи df-api/v2 — краткое описание изменения
before, after	Снимки сущности для событий записи df-api/v2; не используются для операций чтения

Срок хранения журнала задаётся настройками компании; записи доступны на экране Audit Log пользователям с ролью Company Admin или Super Admin.

8 Справочник кодов ошибок

В таблице сведены коды ошибок публичного API.

Код	HTTP	Описание
API_KEY.KEY_MISSING	401	Заголовок X-Api-Key не передан
API_KEY.INVALID_KEY	401	API-ключ не соответствует ни одному сохранённому
API_KEY.INVALID_ENCRYPTED_API_KEY	400	Зашифрованный payload ключа не удалось декодировать
API_KEY.AUTH_FAILED	401	Общий сбой аутентификации
API_KEY.ACCOUNT_LOCKED	403	Пользователь не в статусе ENABLED
API_KEY.IP_BLOCKED	403	IP клиента в чёрном списке или вне белого списка
API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE	403	У компании нет действующей лицензии
DF_API.INVALID_PARAMETER	400	Параметр пути или query не прошёл валидацию; в управлении доступом v2 — недопустимый или отсутствующий accessLevel, попытка поднять уровень выше глобальной роли, недопустимый новый владелец
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize превышает 100
DF_API.INVALID_TYPE	400	Некорректное значение фильтра type для витрин
DF_API.INVALID_MERGE_TYPE	400	Некорректное значение фильтра merge_type для витрин
DF_API.INVALID_DB_TYPE	400	Некорректное значение фильтра db_type для подключений
DF_API.INVALID_STATUS	400	Некорректное значение фильтра status для подключений
DF_API.INVALID_FORMAT	400	format отличается от json и xlsx (для витрин и подключений v2 — от json)
DF_API.VALIDATION_FAILED	400	Тело или query не соответствуют схеме (v2); details[] перечисляет поля
DF_API.PROJECT_NOT_FOUND	404	Проект не существует или недоступен
DF_API.VERSION_NOT_FOUND	404	Версия не существует или недоступна
DF_API.DATA_MART_NOT_FOUND	404	Витрина не существует в указанной версии
DF_API.CONNECTION_NOT_FOUND	404	Подключение не существует в указанной версии
DF_API.DIMENSION_GROUP_NOT_FOUND	404	Группа измерений не существует в указанной версии
DF_API.FACT_TABLE_NOT_FOUND	404	Таблица фактов не существует в указанной версии
DF_API.RELATIONSHIP_NOT_FOUND	404	Связь не существует в указанной версии
DF_API.LICENSE_LIMIT_REACHED	403	Лимит лицензии (например, на число версий) достигнут — создание версии или импорт в новую версию отклонены (v2)
DF_API.WRITE_ACCESS_DENIED	403	Эффективная роль владельца ключа в проекте ниже требуемой; вызывающий не владелец проекта и не администратор (управление доступом v2)
DF_API.INVALID_API_KEY	401	Заголовок X-Api-Key отсутствует или ключ не найден
DF_API.ACCOUNT_LOCKED	403	Владелец ключа деактивирован
DF_API.IP_NOT_ALLOWED	403	IP клиента в чёрном списке или вне белого
DF_API.LICENSE_INVALID	403	У компании нет действующей лицензии
DF_API.MISSING_REQUIRED_FIELD	400	Отсутствует обязательное поле (например, при полной замене PUT) (запись v2)
DF_API.INVALID_ENUM_VALUE	400	Значение select/enum-поля не входит в число допустимых (запись v2)
DF_API.ID_MISMATCH	400	id в теле не совпадает с id в пути (запись v2)
DF_API.INVALID_RELATIONSHIP_TYPE	400	relationship_type должен быть many_to_one (запись v2)
DF_API.INVALID_SOURCE_CONNECTION	400	В объекте источника указано подключение, которого нет в версии проекта (запись v2)
DF_API.INVALID_SOURCE_DB	400	Поле db объекта источника не является именем базы данных указанного подключения (запись v2)
DF_API.INVALID_SOURCE_SCHEMA	400	Указанная схема отсутствует в подключении (только PostgreSQL) (запись v2)
DF_API.INVALID_SOURCE_TABLE	400	Таблица из объекта источника отсутствует в кэшированной схеме подключения (запись v2)
DF_API.INVALID_SOURCE_COLUMN	400	Колонка из объекта источника отсутствует в этой таблице (запись v2)
DF_API.CONNECTION_MISMATCH	400	Ключ связи указывает на подключение, отличное от подключения таблицы фактов или группы измерений (запись v2)
DF_API.INVALID_IDEMPOTENCY_KEY	400	Idempotency-Key не является корректным UUID v4 (запись v2)
DF_API.DUPLICATE_NAME	409	Элемент, проект или версия с таким именем уже существует в области (запись v2)
DF_API.DUPLICATE_RELATIONSHIP	409	Связь для этой пары таблица фактов → группа измерений уже существует (запись v2)
DF_API.DUPLICATE_LEVEL	409	Двум измерениям назначен одинаковый уровень иерархии в группе (запись v2)
DF_API.CONSTRAINT_VIOLATION	409	На элемент ещё есть ссылки, его нельзя удалить или снять назначение (запись v2)
DF_API.IDEMPOTENCY_IN_PROGRESS	409	Запрос с тем же Idempotency-Key ещё выполняется (запись v2)
DF_API.INVALID_FORMULA_SYNTAX	422	Не удалось разобрать формулу показателя (запись v2)
DF_API.FORMULA_REFERENCE_NOT_FOUND	422	Формула показателя ссылается на несуществующий элемент (запись v2)
DF_API.CIRCULAR_DEPENDENCY	422	Формула показателя создаёт циклическую ссылку (запись v2)
DF_API.GLOBAL_VERSION_CONFLICT	422	Нельзя установить is_global — конфликт с другой глобальной версией; тем же кодом отклоняется удаление текущей глобальной версии (запись v2)
DF_API.INVALID_PARAMETER_TYPE	422	Измерение, переданное в периодную функцию формулы, привязано к колонке источника, не являющейся датой или временем (запись v2)
DF_API.BULK_REJECTED	422	Ни одна строка массовой операции не применена (запись v2); частичный успех — 207 Multi-Status
DF_API.SQL_GENERATION_FAILED	422	Не удалось сгенерировать SQL показателя при include_sql=true (v2)
DF_API.RESOURCE_NOT_FOUND	404	Целевой элемент или назначение не существует; целевой пользователь управления доступом не существует или вне компании проекта (запись v2)
DF_API.GIT_CONNECTION_FAILED	422	Git-репозиторий недоступен или отклонил учётные данные (перенос версий, Git-подключения)
DF_API.GIT_PUSH_FAILED	422	Push отклонён: ветка изменилась во время экспорта или защищена (экспорт в Git)
DF_API.UNPROCESSABLE_ENTITY	422	Источник импорта невалиден или превышает лимиты размера (перенос версий)
SQL_GENERATION_FAILED	201/200 (в validation_errors ответа generate-sql)	Витрина не может сейчас сформировать SQL
DF_API.RATE_LIMIT_EXCEEDED	429	Превышена квота 100 запросов / 60 с на ключ (все группы; в v2 code: rate_limit_exceeded)
DF_API.INTERNAL_ERROR	500	Непредвиденная ошибка сервера (v2 отдаёт code: internal_error без внутренних деталей)

В df-api/v2 ключи внутренних сервисов (PROJECT.*, VERSION.*, DATAMART.*, DATAMART_DB.*, GIT_CONNECTION.*, VCS_EXPORT.*, VCS_IMPORT.*, LICENSE.*) перед отправкой клиенту приводятся к ключам DF_API.* из этой таблицы; ключи, для которых нет явного соответствия (в том числе коды управления доступом PROJECT.* и USER.NOT_FOUND), приводятся к общему коду по HTTP-статусу: 400 → DF_API.INVALID_PARAMETER, 401 → DF_API.INVALID_API_KEY, 403 → DF_API.WRITE_ACCESS_DENIED, 404 → DF_API.RESOURCE_NOT_FOUND, 409 → DF_API.CONSTRAINT_VIOLATION, 422 → DF_API.UNPROCESSABLE_ENTITY, 429 → DF_API.RATE_LIMIT_EXCEEDED.