База знаний PMTA›Механизм§ 8.3.4

Как API сообщает об ошибке

HTTP API error reporting

Код 200 при ошибке

Два соглашения в одном узле. Подача по HTTP ведёт себя привычно: ошибка в запросе, ключе, пути, методе или внутри узла — каждой свой код ответа, 400, 403, 404, 405 или 500, а подробности — в теле errors.

API настройки — иначе: всё, кроме отказа в доступе, возвращает 200, а исход пишет в поле status — success или fail — и текст в message. Отклонённое изменение не применяется.

Текст отказа бывает сбивающим: удаление используемого списка может вернуть «no such address list» — удаление отклонено, а список остался на месте. А при большой операции блокировка хранилища может уронить соседнюю операцию или обычное перечитывание — их повторяют.

Главная ловушка — одна обработка ошибок на оба API. Клиент, написанный под коды ответа подачи, примет отклонённое изменение настройки за применённое: код 200 будет и там.

Что делает Хаб. В ответе POST /command Хаб тоже судит по полю status, а не по коду: отказ команды приходит с 200. API настройки Хаб не использует.

Рекомендуемые значения

Как узнать об ошибке:

API	Сигнал ошибки
подача по HTTP	код ответа и тело errors
API настройки	status fail и message при коде 200
отказ в доступе к API настройки	код ответа, отличный от 200

Коды подачи по HTTP, соглашение 200 со status у API настройки, сбивающий текст и блокировки — из руководства (§ 8.1.8–8.1.9, § 8.3, § 8.3.4). Разбор ловушки — наш.

Пример в конфигурации

# отказ API настройки: код 200, исход — в теле
HTTP/1.1 200 Ok
{"message": "Error reading configuration: Config API error: Address 'a@z.com' does not exist in address list 'list1'.", "status": "fail"}

Пример руководства: удаление несуществующего адреса отклонено, а код ответа — успешный.

жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.

Совместимость

PowerMTA 6.0

описана в руководстве этой версии · платформа: любая

С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.

⇄

Связанные записи

2 связи

Где применяется

Настройка через API и файл не сходятсяСмежный механизм: они работают вместе. § 8.3.4 Подача письма по HTTPЗапрос, отдающий то же самое. § 8.1.9

Как проверить на узле

Посмотреть, как узел с включённым API настройки отвечает на запрос несуществующего списка:

curl -s -w '\n%{http_code}\n' 'http://127.0.0.1:8080/config/address-lists/nosuchlist'

Код 200 со status fail — соглашение API настройки: разбирать надо тело.

◇

Что ещё почитать

3 статьи

◇Принять, направить, доставитьПуть письма внутри узла: принять, решить куда, доставить — и между этими тремя шагами живут все настройки.◇Четыре типа значений, на которых написан весь конфигЛогическое, образец домена, регулярное выражение и промежуток времени — определены один раз в § 3.2 и дальше используются всеми директивами.◇Перезагрузка настроек против перезапуска службыКонфигурация читается при старте, дальше правки подхватываются командой перезагрузки — кроме тех директив, которые руководство помечает как требующие перезапуска.

В Хабе

Цена ошибки: безопасно: неверное значение ничего не ломает
Сценарии: Жизненный цикл конфигурации