Сообщение клиента «МойСклад вернул ошибку» обычно теряет самую полезную часть — 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 задаёт ветку, тело объясняет деталь

Класс ответаЧто это обычно означаетДействие
2xxHTTP-запрос принятПроверить ожидаемую структуру ответа
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 должен иметь ограничение попыток, растущую задержку и случайный разброс, чтобы несколько воркеров не повторяли запрос одновременно.

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

Если один и тот же токен читает товары, но не создаёт отгрузку, это ещё не доказывает, что токен неверный. У сотрудника могут отличаться права на тип операции, организацию или склад. При ограничении частоты сначала сократите параллелизм и объедините допустимые операции, а не создавайте новые учётные записи для обхода ограничений.

Пакет диагностики воспроизводит одну ошибку

  1. Записать UTC-время, метод и URL без токена и персональных параметров.
  2. Сохранить status, response headers и JSON errors целиком.
  3. Повторить безопасный GET тем же клиентом и учётными данными.
  4. Сократить failing payload до обязательных полей.
  5. Сверить права сотрудника и ссылки на связанные сущности.
  6. Для записи проверить результат до любого повторного POST.

Инцидент закрыт, когда причина привязана к конкретному status и полю или ограничению, а интеграция различает постоянные и временные ошибки. В рабочем логе оставьте correlation id своего запроса, длительность и безопасный фрагмент ответа; Authorization и персональные данные туда не входят.

Проверенные источники