Сообщение клиента «МойСклад вернул ошибку» обычно теряет самую полезную часть — HTTP status и JSON-тело. Без них 401 из-за токена легко спутать с 400 из-за поля документа или 429 из-за частоты запросов. Первое действие — не менять всё подряд, а записать один полный обмен без секрета авторизации.
Сравните не только URL, но и метод, тело и заголовки. Тот же endpoint может успешно отвечать на GET и отклонять POST; запрос через браузерный плагин может незаметно добавлять заголовок, которого нет у фоновой интеграции.
Минимальный журнал не содержит токен
curl --compressed --request GET \
'https://api.moysklad.ru/api/remap/1.2/entity/product?limit=1' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept-Encoding: gzip' \
--includeКоманда условная: токен берите из защищённого хранилища и не вставляйте в тикет, shell history или общий лог. Официальная документация поддерживает Basic Auth и Bearer token и в примерах использует `Accept-Encoding: gzip`. Для запроса с JSON-телом отдельно проверьте `Content-Type: application/json`.
Status задаёт ветку, тело объясняет деталь
| Класс ответа | Что это обычно означает | Действие |
|---|---|---|
| 2xx | HTTP-запрос принят | Проверить ожидаемую структуру ответа |
| 400/422-подобная ошибка | Поля или бизнес-правило | Читать errors и исправлять payload |
| 401 | Проблема аутентификации | Проверить токен/учётные данные |
| 403 | Недостаточно прав | Сверить пользователя, роль и сущность |
| 404 | Неверный путь или id | Сверить endpoint и UUID |
| 429 | Ограничение частоты | Уменьшить параллелизм и ждать |
| 5xx/timeout | Временный или неопределённый результат | Повторять осторожно |
Точный смысл берите из тела и актуального раздела документации, а не только из таблицы. API возвращает описания ошибок, которые позволяют отличить отсутствующее обязательное поле от недоступного ресурса. Не преобразуйте любой не-200 в фразу «сервер недоступен».
Запрос сверяют с контрактом ресурса
- Путь начинается с актуальной версии `/api/remap/1.2/` и нужного типа сущности.
- HTTP-метод соответствует операции над списком или отдельным объектом.
- UUID взят из meta.href той же сущности, а не из внешней системы.
- В ссылочных полях передаётся meta с допустимым type и href.
- Параметры `limit`, `expand`, `fields` и filter отвечают ограничениям документации.
- Дата, число и enum сериализованы в ожидаемом формате.
- Сотрудник действительно имеет права на организацию, склад и операцию.
Полезно уменьшить failing request: оставить одно действие и минимально обязательные поля. Если сокращённое тело проходит, возвращайте поля группами. Это быстрее обнаруживает неправильную ссылку или значение, чем сравнение большого JSON глазами.
Повтор чтения и повтор записи — не одно и то же
| Операция | После timeout | Защита |
|---|---|---|
| GET списка | Обычно можно повторить | Та же пагинация и фильтр |
| GET объекта | Обычно можно повторить | Тот же id |
| PUT известного id | Проверить состояние и повторить осознанно | Сравнение updated/version |
| POST создания | Не повторять вслепую | Поиск по externalCode/ключу |
| Массовая операция | Проверить каждый результат | Малые партии и журнал |
Timeout означает, что клиент не получил ответ, но сервер мог завершить операцию. Перед вторым POST запросите сущность по заранее назначенному устойчивому идентификатору. Автоматический retry должен иметь ограничение попыток, растущую задержку и случайный разброс, чтобы несколько воркеров не повторяли запрос одновременно.
Права и лимиты проверяют без смены секрета наугад
Если один и тот же токен читает товары, но не создаёт отгрузку, это ещё не доказывает, что токен неверный. У сотрудника могут отличаться права на тип операции, организацию или склад. При ограничении частоты сначала сократите параллелизм и объедините допустимые операции, а не создавайте новые учётные записи для обхода ограничений.
Пакет диагностики воспроизводит одну ошибку
- Записать UTC-время, метод и URL без токена и персональных параметров.
- Сохранить status, response headers и JSON errors целиком.
- Повторить безопасный GET тем же клиентом и учётными данными.
- Сократить failing payload до обязательных полей.
- Сверить права сотрудника и ссылки на связанные сущности.
- Для записи проверить результат до любого повторного POST.
Инцидент закрыт, когда причина привязана к конкретному status и полю или ограничению, а интеграция различает постоянные и временные ошибки. В рабочем логе оставьте correlation id своего запроса, длительность и безопасный фрагмент ответа; Authorization и персональные данные туда не входят.