Коды ошибок REST API модуля ithive.ipr

Методы ipr.* возвращают ошибки в конверте модуля (Vibe API) внутри стандартной обёртки Bitrix REST.

Полный перечень кодов совпадает с IPR\Rest\RestApi. На страницах методов указаны только актуальные для конкретного endpoint'а коды — этот справочник содержит все коды модуля.

Формат ответа при ошибке

{
          "result": {
            "result": null,
            "total": null,
            "next": null,
            "error": {
              "code": "VALIDATION_ERROR",
              "message": "Required parameter \"userId\" must be a positive integer",
              "details": {
                "field": "userId"
              }
            }
          },
          "time": {}
        }

details опционален (часто field, id, userId, allowed и т. п.). Ошибки доменных сервисов (ipr.employee.update, ipr.point.set, ipr.course.review.*) дополнительно несут машинный ключ details.reason — он описан на страницах методов.

HTTP-статус

HTTP-статус ответа выставляется по коду ошибки (RestApi::getHttpStatusForCode). Важная особенность модуля: коды, не перечисленные явно в таблице ниже как 401/403/500, отдаются с HTTP 400 (в том числе NOT_FOUND и METHOD_NOT_FOUND) — в отличие от привычного REST-соглашения «404 для NOT_FOUND». Ориентируйтесь на поле error.code в теле ответа, а не только на HTTP-статус.

Общие коды

Код	HTTP	Когда возникает
`UNAUTHORIZED`	401	Пользователь не авторизован (нет пользователя в контексте REST-вызова)
`PERMISSION_DENIED`	403	Недостаточно прав на операцию или сущность. В коде также встречается алиас `ERROR_ACCESS_DENIED` — это то же самое значение `PERMISSION_DENIED`, отдельного кода `ACCESS_DENIED` в ответах нет
`VALIDATION_ERROR`	400	Некорректные, неполные или несовместимые параметры запроса
`NOT_FOUND`	400	Сущность не найдена или недоступна вызывающему
`INVALID_LIMIT`	400	`limit` не является положительным целым числом
`LIMIT_EXCEEDED`	400	`limit` больше 500
`INVALID_OFFSET`	400	`offset` отрицательный
`INVALID_FILTER`	400	Некорректная структура `filter` (например, пустой массив в `$in`/`$nin`) либо неизвестное поле фильтра (`details.field`)
`INVALID_FILTER_OPERATOR`	400	Неизвестный оператор фильтра (разрешены `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`)
`FETCH_ALL_LIMIT_EXCEEDED`	400	При `fetchAll=true` количество подходящих записей больше 5000
`METHOD_NOT_FOUND`	400	Метод REST не зарегистрирован (зарезервированный код; фактически на неизвестный метод отвечает REST-движок Bitrix)
`NOT_IMPLEMENTED`	400	Метод зарегистрирован, но бизнес-логика ещё не реализована
`IPR_ALREADY_EXISTS`	400	У сотрудника уже достигнут лимит активных ИПР/ПИС (опция модуля «Количество возможных программ», по умолчанию 2)
`FILE_TOO_LARGE`	400	Загружаемый файл превышает лимит размера (зарезервировано)
`INTERNAL_ERROR`	500	Непредвиденная ошибка на сервере. Сообщение всегда общее: `Internal error`; причина — в `error.details.reason` (если есть), подробности пишутся только в журнал сервера

Сообщения VALIDATION_ERROR, NOT_FOUND и PERMISSION_DENIED адресованы пользователю и приходят без изменений; внутренние детали (тексты исключений) клиенту не отдаются.

Специфичные для методов ситуации

ipr.ipr.add / ipr.programtemplate.launch / ipr.programtemplate.masslaunch — при достижении лимита активных программ у сотрудника: IPR_ALREADY_EXISTS.
ipr.ipr.draft.add — те же коды и условия, что у ipr.ipr.add (включая IPR_ALREADY_EXISTS), карточка при этом не создаётся. ipr.ipr.draft.get — черновик не найден: NOT_FOUND (details.reason = draft_not_found); черновик другого пользователя у непривилегированного актора: PERMISSION_DENIED (details.reason = draft_foreign); payload больше 256 КБ: VALIDATION_ERROR (details.reason = draft_payload_too_large).
ipr.ipr.update (смена status), ipr.ipr.complete / approve / reject / reopen — недопустимый переход статуса из текущего состояния карточки: VALIDATION_ERROR (поле status в details).
ipr.ipr.delete, ipr.action.delete (без force) — попытка удалить карточку/обязательное действие без прав или в неудаляемом состоянии: PERMISSION_DENIED.
ipr.test.attempt.start — если у теста нет привязанных вопросов: VALIDATION_ERROR; исчерпан лимит попыток теста (details.limit): VALIDATION_ERROR; userId не совпадает с текущим пользователем: PERMISSION_DENIED; тест неактивен или недоступен по ACL обучения: NOT_FOUND.
ipr.test.attempt.answer — вопрос не относится к попытке или попытка уже завершена (STATUS = F): VALIDATION_ERROR / NOT_FOUND; на вопрос уже дан ответ (повторный ответ запрещён): VALIDATION_ERROR.
ipr.lesson.add / relation.update, ipr.question.add, ipr.test.add / update — урок не входит в дерево указанного курса: PERMISSION_DENIED (details.lessonId, details.courseId).
Методы, зависящие от модуля iblock или learning (все, кроме currentUser/schema/history.*): если модуль не подключён на портале — INTERNAL_ERROR.