Обработка ошибок JSON API

Ошибки JSON API 1.2 МойСклад возвращаются в едином формате с массивом errors, кодом, HTTP-статусом и подсказкой. Умение их разбирать превращает интеграцию из хрупкой в предсказуемую и самодиагностируемую.

Формат тела ошибки

При ошибке МойСклад возвращает соответствующий HTTP-статус и тело с массивом errors. Каждый элемент описывает одну проблему:

{"errors":[{"error":"Не указано обязательное поле name","code":3000,"moreInfo":"https://dev.moysklad.ru/doc/api/remap/1.2/#error_3000","parameter":"name"}]}

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

HTTP-статусы

HTTP-код задаёт крупную категорию проблемы, а поле code уточняет причину. Ключевые статусы:

Правило разбора: сначала смотрим статус, чтобы понять, повторять ли запрос, затем — код и parameter, чтобы понять, что именно исправить.

Клиентские и серверные ошибки

Стратегия обработки радикально зависит от того, чья это ошибка.

• 4xx — ваша ошибка. Повтор без изменения запроса бесполезен: нужно исправить данные или права. Исключение — 429, который повторяют после паузы.
• 5xx — ошибка сервиса. Запрос корректен, имеет смысл повторить с задержкой (экспоненциальный backoff).
• Сетевые таймауты обрабатываются как временные — повтор с осторожностью и идемпотентностью.

Ошибки в массовых запросах

Отдельный случай — ошибки внутри массовых операций. При частичном сбое пачки HTTP-код остаётся 200, а сбойные элементы возвращаются объектом с полем errors на своей позиции в массиве результата.

• Всегда разбирайте ответ массовой операции поэлементно.
• Сопоставляйте позицию ошибки с исходным элементом по индексу.
• Успешные элементы применены — повторять нужно только сбойные.

Логирование и диагностика

Чтобы ошибки было легко расследовать, фиксируйте контекст каждого сбойного запроса:

1. Метод, URL и тело запроса (без секретов).
2. HTTP-статус и полное тело ответа с массивом errors.
3. Значения code и parameter — по ним удобно строить агрегаты «какие ошибки чаще».
4. Идентификатор вашей сущности, чтобы связать сбой с бизнес-объектом.

Такой лог позволяет за минуты понять, что именно и почему не синхронизировалось, без повторения запроса вручную.

Централизованный обработчик

Разбор ошибок стоит вынести в один слой клиента, а не дублировать по коду:

• Единая функция парсит тело, вытаскивает первый (или все) элемент errors и бросает типизированное исключение.
• Класс исключения зависит от статуса: авторизация, валидация, лимит, серверная ошибка.
• Политика повторов задаётся в одном месте на основе типа исключения.
• Так бизнес-код работает с понятными исключениями, а не с сырыми HTTP-ответами.

Полезно завести словарь известных кодов code с рекомендованной реакцией: одни ошибки требуют вмешательства оператора (нет прав, дубликат), другие — автоматического повтора, третьи — постановки сущности в карантин до ручного разбора. Такой словарь превращает разрозненные ответы сервиса в управляемый набор сценариев и упрощает поддержку интеграции.

Итог

Ошибки JSON API 1.2 приходят массивом errors с полями error, code, parameter и moreInfo. HTTP-статус задаёт категорию: 4xx — исправляйте запрос (кроме 429), 5xx — повторяйте с backoff. В массовых операциях сбои прячутся в теле при коде 200. Централизуйте разбор и логируйте code и parameter — это делает интеграцию самодиагностируемой.

Мы в B2Bsite закладываем такой слой обработки ошибок в каждую интеграцию с МойСклад: типизированные исключения, политика повторов и подробные логи, чтобы сбои были видны сразу и не превращались в тихую потерю данных.