Коды ошибок

Структура ответа об ошибке

Сервер возвращает ошибки в едином формате:

{
  "result": false,
  "errorId": "ea244925-8316-4f7c-9047-895020e61720",
  "errorMessage": "Описание ошибки",
  "errorCode": "51.203",
  "operationCode": "51.060",
  "errorData": { }
}

Поле	Описание
`result`	Всегда `false` при ошибке
`errorId`	UUID ошибки — передайте в поддержку для быстрого поиска причины
`errorMessage`	Текстовое описание ошибки
`errorCode`	Формальный код ошибки для программной обработки
`operationCode`	Код операции, которая вызвала ошибку
`errorData`	Дополнительные данные (опционально)

HTTP-статусы

Статус	Описание	Типичные причины
400	Bad Request	Невалидные данные, не заполнены обязательные поля, нарушено бизнес-правило
401	Unauthorized	Невалидный или просроченный токен, не указаны заголовки для работы от имени пользователя
403	Forbidden	Недостаточно прав, пользователь не относится к клиенту
404	Not Found	Сервер не нашёл сущность по `id` или `externalId`
429	Too Many Requests	Клиент превысил лимит запросов

Ошибки аутентификации (401)

Отсутствуют заголовки для работы от имени пользователя

Симптом: 401 при использовании мастер-токена.

Причина: Не указаны обязательные заголовки Impersonated-User-Id и Impersonated-User-Id-Type.

Решение: Добавьте оба заголовка. См. Заголовки для работы от имени пользователя.

Некорректный издатель токена (51.203)

{
  "errorCode": "51.203",
  "errorMessage": "Указанный издатель токена аутентификации некорректен.",
  "errorData": { "iss": "MTT" }
}

Причина: Неправильное значение iss в JWT Bearer-токена.

Решение: Используйте точное значение iss, полученное при регистрации интегратора в Службе заботы.

HRlink не может проверить подпись

Причина: в Службу заботы передали публичный ключ вместо сертификата, либо клиент подписывает JWT не тем приватным ключом.

Решение: передайте в Службу заботы сертификат (не публичный ключ) и подписывайте JWT приватным ключом от этого сертификата.

Заголовок с ID пользователя отсутствует (22.050)

{
  "errorCode": "22.050",
  "errorMessage": "Заголовок с ID пользователя отсутствует в запросе."
}

Причина: При использовании мастер-токена не указан заголовок Impersonated-User-Id.

Решение: Добавьте заголовки Impersonated-User-Id и Impersonated-User-Id-Type.

User-Api-Token перестал работать

Причина: Истёк срок действия (1 год) или пользователь заблокирован/уволен.

Решение: Выпустите новый токен в интерфейсе кадровика.

Ошибки прав доступа (403)

Пользователь не имеет прав на операцию

Причина: у пользователя, от имени которого клиент выполняет запрос, нет нужной роли или права.

Решение:

Убедитесь, что пользователь является кадровиком (HR) или делопроизводителем (CLERK) в нужном юрлице
Проверьте наличие конкретного права (например, DOCUMENTS_CREATE)
Убедитесь, что пользователь относится к указанному clientId

Ошибки валидации данных (400)

Не указаны получатели документа (13.1551)

{
  "errorCode": "13.1551",
  "errorMessage": "Не указаны получатели документа.",
  "errorData": { "documentIndex": 0 }
}

Причина: для маршрута с этапом RECEIVING клиент не указал наблюдателей.

Решение: Добавьте watcherIds или watcherExternalIds и заполните participants.

Нельзя указывать участников маршрута

Причина: клиент передал participants при signingOrder != ROUTE.

Решение: Уберите participants или измените signingOrder на ROUTE. См. матрицу совместимости.

Конфликт версий (optimistic locking)

Причина: переданная version не совпадает с текущей версией сущности в базе — другой клиент или пользователь изменил сущность параллельно.

Решение: Получите актуальную версию сущности (GET) и повторите запрос с обновлённой version. См. optimistic locking.

Сервер не смог сконвертировать файл в PDF/A

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

Решение:

Проверьте файл, загрузив его через интерфейс HRlink
Убедитесь, что формат из списка допустимых
Проверьте корректность multipart/form-data запроса

PUT затирает данные null

Симптом: после обновления сотрудника через PUT у него пропали externalId, tags, номер или другие поля, которые клиент не менял.

Причина: PUT в API HRlink — это полная замена всех полей, а не частичное обновление. Любое поле, которое клиент не передал в теле запроса, сервер трактует как null.

Решение: получите текущее состояние сущности GET-запросом, измените нужные поля, отправьте PUT с полным набором полей. Альтернативы через PATCH нет. Подробнее — Поведение PUT.

Невалидные реквизиты юрлица

Причина: клиент передал ИНН, ОГРН или КПП в неверном формате (ИНН — 10 или 12 цифр, ОГРН — 13 или 15 цифр).

Решение: проверьте формат реквизитов. КПП обязателен для ЮЛ (ИНН 10 цифр), опционален для ИП (ИНН 12 цифр).

Максимум элементов в bulk sync превышен

Причина: в массиве data задачи Создать задачу синхронизации больше 500 элементов.

Решение: разбейте данные на порции по 500 элементов.

Активная задача синхронизации блокирует операцию

Причина: клиент пытается создать задачу синхронизации того же типа, пока предыдущая не завершилась.

Решение: дождитесь завершения предыдущей задачи. Проверьте статус методом Статус задачи синхронизации.

Ошибки загрузки файлов

Unexpected end of input

Причина: неправильная структура multipart/form-data — последний boundary не заканчивается на --.

Решение: убедитесь, что завершающий boundary содержит -- в конце. См. типичные ошибки загрузки.

Недопустимое расширение файла

Причина: расширение файла не входит в список допустимых.

Решение: используйте один из допустимых форматов: .pdf, .doc, .docx, .rtf, .xls, .xlsx, .jpeg, .jpg, .bmp, .png, .tiff.

Ошибки при работе с participantId

participantId не найден (13.1914)

Симптом: HTTP 404, errorCode: 13.1914, errorMessage: "По заданному ID не найден участник этапа маршрута подписания".

Причина: администратор сохранил изменения шаблона маршрута между запросом шаблона и отправкой документа. HRlink пересоздаёт всех участников при любом сохранении шаблона, поэтому переданный participantId больше не существует.

Решение: перезапросите шаблон маршрута, сопоставьте своих сотрудников с новыми participantId и повторите запрос на подписание. Ошибка ретраибельна. Подробнее — participantId — критически важная деталь.

Как избегать постоянно: сохраняйте version шаблона из предыдущего ответа и сверяйте с текущей перед отправкой. Если совпадает — participantId валидны, отдельный запрос не нужен.

Структура ответа об ошибке​

HTTP-статусы​

Ошибки аутентификации (401)​

Отсутствуют заголовки для работы от имени пользователя​

Некорректный издатель токена (51.203)​

HRlink не может проверить подпись​

Заголовок с ID пользователя отсутствует (22.050)​

User-Api-Token перестал работать​

Ошибки прав доступа (403)​

Пользователь не имеет прав на операцию​

Ошибки валидации данных (400)​

Не указаны получатели документа (13.1551)​

Нельзя указывать участников маршрута​

Конфликт версий (optimistic locking)​

Сервер не смог сконвертировать файл в PDF/A​

PUT затирает данные null​

Невалидные реквизиты юрлица​

Максимум элементов в bulk sync превышен​

Активная задача синхронизации блокирует операцию​

Ошибки загрузки файлов​

Unexpected end of input​

Недопустимое расширение файла​

Ошибки при работе с participantId​

participantId не найден (13.1914)​

Рекомендации по обработке ошибок​