> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/ru/developers/api/errors.md).

# Ошибки

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

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

```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`, в виде дополнительных полей верхнего уровня.

> **Note**
>
> Вы можете передать собственный заголовок запроса `X-Correlation-Id`, чтобы связать свои трассировки с нашими. То же значение вернётся в ответе и в `correlationID`.

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

| Статус | Значение | Что делать |
| --- | --- | --- |
| `400` | Запрос недопустим, или режим команды не поддерживает этот эндпоинт | Исправьте запрос — в `errors` перечислены недопустимые поля. Не повторяйте его без изменений. |
| `401` | API-токен не передан или недействителен | Проверьте заголовок `Authorization`. См. [Аутентификация](https://www.boxhero.io/docs/ru/developers/api/authentication). |
| `403` | BoxHero отклонил изменение — например, оно нарушает правило учёта остатков или переданный `revision` устарел | Посмотрите причину в `code`. Прежде чем повторить запрос, исправьте его или получите актуальные данные. |
| `404` | Ресурс не существует в этой команде или был удалён | Проверьте id. Не повторяйте запрос без изменений. |
| `429` | Слишком много запросов | Подождите и повторите попытку. См. [Ограничение частоты запросов](https://www.boxhero.io/docs/ru/developers/api/rate-limiting). |

Типы ошибок, которые может вернуть каждый эндпоинт, указаны у него в [справочнике API](https://www.boxhero.io/docs/ru/developers/api/reference).

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

Чтобы [изменить](https://www.boxhero.io/docs/ru/developers/api/reference/transactions/update-transaction) или [удалить](https://www.boxhero.io/docs/ru/developers/api/reference/transactions/delete-transaction) операцию, передайте последний известный вам `revision`. Если за это время кто-то другой изменил операцию, API отклонит запрос с `403` и `code`, равным `tx-modify-revision-mismatch`. Ветвите логику по `code`: снова получите операцию, проверьте изменение и повторите запрос с новым `revision`.

```js
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.
  }
}
```