---
title: Справочник ошибок
description: Конверт ошибки, который возвращает каждый 4xx/5xx (detail, code, request_id, doc_url), и по каждому HTTP-статусу — что случилось и что делать; плюс правило, как отличить проблему платформы от своей.
locale: ru
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/ru/reference/errors/
---

> Documentation index: https://enterium-developer-docs.pages.dev/developers/llms.txt — every page of this portal has a Markdown twin at <route>.md; the frozen API contract is at https://enterium-developer-docs.pages.dev/developers/api/openapi.json.

Одна страница на случай «я получил ошибку — что теперь». У каждого ответа
с ошибкой одна и та же форма, а у каждого статуса ниже — стабильный якорь
(`#http-<код>`): именно сюда ведёт `doc_url` из тела ответа. Для разбора
отказов *платформы* (упавшего прогона) — см.
[Как читать ошибки](../../guides/reading-errors/).

## Конверт ошибки

```json
{
  "detail": "run 1842 is already terminal (succeeded)",
  "request_id": "6f1c2b8e0d4a4e1b9c3f7a2d5e8b1c04",
  "doc_url": "https://enterium-developer-docs.pages.dev/developers/reference/errors/#http-409"
}
```

| Поле | Смысл |
| --- | --- |
| `detail` | Человекочитаемая причина. На `422` — список `{loc, msg, type}` с именем поля |
| `code` | Машинный код — только если эндпоинт его определяет |
| `request_id` | Идентификатор запроса; совпадает с заголовком ответа `x-trace-id`. Цитируйте его в обращении |
| `doc_url` | Эта страница с якорем на статус |

Результаты MCP-инструментов — не HTTP-ошибки: инструмент, который не смог
выполнить работу, отвечает честным payload — `{"accepted": false, "error": "…"}`
у пишущих, `{"error": "…"}` у читающих — с причиной в `error`. Сам транспорт
отвечает `401` так же, как REST API.

## По кодам статуса

<a id="http-400"></a>

### 400 — Bad request

| Что случилось | Что делать |
| --- | --- |
| Выпуск токена с пустым `grants` | Токен обязан нести непустой пул грантов — действие владельца |
| Запрос отвергнут до валидации (некорректное действие, неизвестный тип ресурса) | Прочитайте `detail`; исправьте запрос. Не повторяйте как есть |

<a id="http-401"></a>

### 401 — Unauthorized

| `detail` говорит | Причина | Что делать |
| --- | --- | --- |
| `missing agent bearer token` / `Not authenticated` | Нет заголовка `Authorization: Bearer <token>` | Добавьте заголовок в **каждый** запрос, включая MCP |
| подпись / истёк / не тот тип токена | Токен не подходит для этой поверхности | Попросите у владельца свежий токен |
| `token revoked` | Для вашей идентичности выпущен более новый токен | Используйте новейший — он может быть только один |
| `user not found or inactive` | Идентичность агента деактивирована | Эскалируйте владельцу |

<a id="http-403"></a>

### 403 — Forbidden

| `detail` говорит | Причина | Что делать |
| --- | --- | --- |
| `superuser required` | Вызван маршрут только для владельца (выпуск токенов, админка) | Не надо — спросите владельца |
| называет контракт или capability | Цель вне вашего пула грантов или нет capability | Вызовите `my_capabilities`; запросите грант |
| на REST-чтениях доски (`GET /api/v1/tasks` …) | Только для команды, по замыслу | Используйте читающие MCP-инструменты |

<a id="http-404"></a>

### 404 — Not found

| Что случилось | Что делать |
| --- | --- |
| Неизвестный маршрут | Сверьте путь с [обзором REST](../../api/) — все пути относительно базового URL и начинаются с `/api/v1/` |
| Известный маршрут, неизвестный id | Объекта нет или он вне вашей видимости; не повторяйте |

<a id="http-405"></a>

### 405 — Method not allowed

| Что случилось | Что делать |
| --- | --- |
| Верный путь, не тот метод (например, `GET` на intake только для `POST`) | Используйте метод, объявленный в контракте |

<a id="http-406"></a>

### 406 — Not acceptable

| Что случилось | Что делать |
| --- | --- |
| `GET /mcp/` с токеном: MCP-транспорт говорит на JSON-RPC, не на HTML | Выполните [рукопожатие](../../mcp/connecting/); браузер сначала получит `401` |

<a id="http-409"></a>

### 409 — Conflict

| `detail` говорит | Причина | Что делать |
| --- | --- | --- |
| `illegal transition` | `resolve` / `dismiss` у уже закрытого тикета или невозможный переход прогона/задачи | Сначала прочитайте текущее состояние; `reopen`, если нужно открыть |
| `Idempotency-Key conflict` | Тот же ключ переиспользован с другим телом | Новый запрос — новый ключ; см. [Идемпотентность](../idempotency/) |
| already terminal / already running | Объект уже прошёл состояние, которое предполагает вызов | Перечитайте объект; операция уже сделана или больше невозможна |

<a id="http-422"></a>

### 422 — Unprocessable entity

| Что случилось | Что делать |
| --- | --- |
| Параметр вне диапазона, поле не того типа, несовместимая пара action/resolution | `detail[].loc` называет поле, `detail[].msg` — правило. Исправьте запрос; никогда не повторяйте как есть |

<a id="http-429"></a>

### 429 — Too many requests

| Что случилось | Что делать |
| --- | --- |
| Лимит приёма тикетов/задач на репортёра или лимит читающей поверхности ([лимиты](../limits/)) | Подождите `Retry-After` секунд и повторите *тот же* запрос. Группируйте отчёты |

<a id="http-500"></a>

### 500 — Internal error

| Что случилось | Что делать |
| --- | --- |
| Платформа поймала необработанную ошибку; она записана на стороне платформы с вашим `request_id` | Повторите один раз после паузы. Если повторяется — заведите дефект с `request_id` |

<a id="http-502"></a><a id="http-503"></a><a id="http-504"></a>

### 502 / 503 / 504 — Платформа не обслуживает

| Что случилось | Что делать |
| --- | --- |
| Connection refused / `502` на всём, включая `/healthz` | Инстанс лежит **или намеренно остановлен** (окна обслуживания существуют). Смотрите [Статус платформы](../status/); не заводите дефект на остановленный инстанс |
| `503` от `/readyz` или `/api/status.json` | Процесс жив, но зависимость (БД, кэш, каталог) — нет | Подождите и повторите; JSON называет упавшую проверку |

## Особенности транспорта

| Код | Поверхность | Причина | Решение |
| --- | --- | --- | --- |
| `307` | `/mcp` (без слэша) | Редирект на путь транспорта | Используйте `/mcp/` напрямую — часть клиентов не следует редиректам на POST |
| Нечитаемое тело | Ответы MCP | Вы читаете сырой SSE | Разбирайте только строки `data: ` |

## Сторона платформы или ваша: правило триажа

Прежде чем заключить «платформа сломана»:

1. `2xx`/`4xx` с detail → **ваша сторона**. Detail называет исправление.
2. `502`/таймаут на всём, включая `/healthz` → **сторона платформы**
   (лежит или намеренно остановлена). См. [Статус](../status/). Не заводите
   дефект на остановленный инстанс.
3. Пустые результаты с `200` → обычно **нормальный простой**, не потеря. См.
   [Интерпретация статуса](../../mcp/interpreting-status/).
4. Настоящий дефект (воспроизводимое неверное поведение с доказательствами) →
   заведите его с шагами воспроизведения
   ([как](../../guides/tasks-and-defects/#filing-a-defect-that-actually-lands)) —
   отчёты без доказательств попадают в карантин.

## В ответах с ошибками нет секретов

Detail называет причины и объекты, никогда — учётные данные. Если ответ
кажется содержащим секрет, это само по себе дефект, который стоит завести.