Ошибки и действия клиента

Все JSON-ошибки имеют общий конверт. Поле request_id в теле отсутствует; для диагностики сохраните новый заголовок X-Request-Id, HTTP-код, error.code и ID операции, если он известен. Не записывайте Bearer или полные секреты в журнал интеграции.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Проверьте поля запроса.",
    "fields": {"contacts.0.phone": ["Укажите телефон."]}
  }
}

Отсутствующие fields/details не заменяются обязательным null. В details могут находиться operation_id, версия или доступные ссылки на конфликтующие ресурсы. Текст сообщения не используйте как условие программы. SQL, сведения о внутренних вызовах и секреты не входят в публичную ошибку. Код 404 не позволяет различить отсутствие записи и недостаточный доступ.

Общие коды

Конкретная операция может вернуть дополнительные коды ограничений ресурса. Их перечень по ресурсам дополняет таблицу HTTP-ответов у каждого метода. Ошибки транспорта могут возникнуть до обработки контроллером и действуют также там, где автоматически полученная таблица ответов не повторяет все общие отказы.

Ошибки ресурсов

Коды предупреждений в meta.warnings не являются ошибками HTTP. Например, ручное назначение может завершиться с предупреждением CREW_OVERLAP или CREW_UNAVAILABLE. Повтор принятой команды сохраняет исходные предупреждения. Автоматическое применение маршрута использует более строгие ограничения из его контракта.

Безопасное восстановление

При сетевом сбое, превышение времени ожидания и 5xx сохраняйте исходный запрос и повторяйте его с прежним Idempotency-Key. При известном operation_id сначала можно прочитать журнал. Если исправляете уже принятое действие или разрешили конфликт версии, используйте новый ключ для нового запроса. needs_reconciliation и EXTERNAL_EFFECT_RECONCILIATION_REQUIRED требуют сверки; автоматическое создание повторного изменения под новым ключом не допускается.

При опросе и повторе 429/503 учитывайте Retry-After, добавляйте задержку и ограничивайте параллелизм на подключение. Лимиты сервера могут настраиваться; повторный запрос также расходует HTTP-квоту. Правила повторов.