Ошибки

Разберитесь в формате ошибок, которые возвращает BoxHero API, и в том, как обрабатывать ошибки в своём коде.

Если запрос завершается неудачей, BoxHero API отвечает HTTP-статусом ошибки и единым JSON-объектом с описанием ошибки:

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "type": "/errors/not-found",
  "title": "No item with id 12345 found in this team.",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "instance": "/items/12345"
}

Поля

Поле	Описание
`id`	Уникальный ID ошибки: `ex_`, за которым следуют 32 шестнадцатеричных символа в нижнем регистре. Укажите его при обращении в поддержку.
`type`	Стабильный машиночитаемый код ошибки. Ветвите логику кода по нему, а не по `title`.
`title`	Краткое описание для человека на английском языке. Формулировка может меняться.
`correlationID`	ID запроса: `rq_`, за которым следуют 32 шестнадцатеричных символа в нижнем регистре; совпадает с заголовком ответа `X-Correlation-Id`. По нему мы находим ваш запрос в наших журналах.
`instance`	Ресурс, на котором произошла ошибка, например `/items/12345`. Путь указывается без префикса `/v1`.
`code`	Уточнённая причина ошибки, например `tx-modify-revision-mismatch`. Присутствует не всегда. Сначала ветвите логику по `type`, затем — для более точной обработки — по `code`.
`errors`	Сведения по отдельным полям; присутствуют в ответах `/errors/invalid-request` (`400`). Каждая запись содержит `path`, указывающий на недопустимое поле, и понятное человеку сообщение `message`.

Некоторые ошибки также содержат id связанного ресурса, например item_id или order_id, в виде дополнительных полей верхнего уровня.

Распространённые коды статуса

Статус	Значение	Что делать
`400`	Запрос недопустим, или режим команды не поддерживает этот эндпоинт	Исправьте запрос — в `errors` перечислены недопустимые поля. Не повторяйте его без изменений.
`401`	API-токен не передан или недействителен	Проверьте заголовок `Authorization`. См. Аутентификация.
`403`	BoxHero отклонил изменение — например, оно нарушает правило учёта остатков или переданный `revision` устарел	Посмотрите причину в `code`. Прежде чем повторить запрос, исправьте его или получите актуальные данные.
`404`	Ресурс не существует в этой команде или был удалён	Проверьте id. Не повторяйте запрос без изменений.
`429`	Слишком много запросов	Подождите и повторите попытку. См. Ограничение частоты запросов.

Типы ошибок, которые может вернуть каждый эндпоинт, указаны у него в справочнике API.

Обработка конфликта версий

Чтобы изменить или удалить операцию, передайте последний известный вам revision. Если за это время кто-то другой изменил операцию, API отклонит запрос с 403 и code, равным tx-modify-revision-mismatch. Ветвите логику по code: снова получите операцию, проверьте изменение и повторите запрос с новым revision.

const res = await fetch(`https://rest.boxhero-app.com/v1/transactions/${id}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ revision, memo: "Recounted" }),
});

if (res.status === 403) {
  const error = await res.json();
  if (error.code === "tx-modify-revision-mismatch") {
    // Fetch the transaction again, check the change, then retry with its new revision.
  }
}