---
title: Как читать ошибки
description: Единый сток ошибок платформы — форма error-события, фильтры GET /api/v1/errors и стандартный маршрут разбора упавшего прогона.
locale: ru
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/ru/guides/reading-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.

Каждый пойманный отказ платформы попадает в один долговечный **сток
ошибок**, читаемый одним эндпоинтом. Если что-то пошло не так — смотреть
сначала сюда.

## Эндпоинт

```sh
curl -fsS "https://entherium.duckdns.org:8443/api/v1/errors?limit=20" \
  -H "Authorization: Bearer <TOKEN>"
```

Фильтры (все опциональны, комбинируются по AND):

| Параметр | Значение |
| --- | --- |
| `source` | Где случилось: `http`, `background-loop`, `batch`, `sse`, `startup` |
| `operation` | Стабильная метка операции, напр. `POST /api/v1/runs` или `projector` |
| `since` | UTC-datetime — только события после этого момента |
| `limit` | 1–500, по умолчанию 100; новые первыми |

## Форма одного события

```json
{
  "guid": 123,
  "source": "batch",
  "operation": "generate step_07",
  "exc_type": "StepError",
  "error": "…сообщение, обрезано на 2000 символах…",
  "context": { "run_guid": 456, "contract": 789 },
  "createtime": "2026-07-23T02:14:05Z"
}
```

`context` — словарь релевантных идентификаторов с вымаранными секретами;
может быть null. По нему сшивай прогон и контракт.

## Стандартный маршрут: «прогон упал — что случилось?»

1. Зафиксируй время старта прогона (из записи прогона или отчёта).
2. Возьми ошибки с этого момента по батч-работе:

   ```sh
   curl -fsS "https://entherium.duckdns.org:8443/api/v1/errors?since=<RUN_START_UTC>&source=batch&limit=50" \
     -H "Authorization: Bearer <TOKEN>"
   ```

3. Читай `operation` (какой шаг), `exc_type` и `error` (что сломалось),
   `context` (какой прогон/контракт).
4. Пусто — расширь: убери `source`; отказ мог случиться в фоновом лупе
   (`source=background-loop`), а не в самом батче.
5. Сверь с `run_step`-записями прогона: упавший шаг и error-событие
   должны сходиться. Запись прогона — истина о том, *где* остановилось;
   error-событие — о том, *почему*.

## Оговорки

- **Сток — best-effort по дизайну.** Запись асинхронная; крэш на старте
  процесса (до запуска event loop) может оставить только строку лога без
  события. Поэтому отсутствие error-события — более слабое свидетельство,
  чем его наличие.
- **Философия fail-loud:** шаги платформы не глотают ошибки в дефолты,
  поэтому реально упавший прогон виден либо здесь, либо в его
  step-записях — тишина плюс завершённый прогон означает успех, а не
  скрытый отказ.