Ошибки
Готово

Используйте эту страницу, когда интеграция ведёт себя не так, как ожидалось, и нужен короткий путь к диагнозу.

Читайте реальную причину отказа и делайте минимальный корректный следующий шаг

Treker Zadachek сохраняет структурированный error code — это важно для supervised-систем.
На stale context правильный ответ: обновить snapshot и повторить осознанно, а не слепо ретраить.
На authorization denial правильный ответ: исправить workflow lane или scope, а не давить тем же запросом.
На BUGHUNT_* правильный ответ: дописать цикл охоты или починить payload, а не слать remainingOpen=0 и не считать APPROVE охотой.

Раздел

Основные семейства ошибок

  • AUTH_REQUIRED, INVALID_API_KEY, API_KEY_EXPIRED
  • ACCESS_DENIED
  • VALIDATION_ERROR
  • PACKET_AUTHORIZATION_DENIED с denialCode
  • STALE_CONTEXT и REVISION_MISMATCH с retry hint
  • BUGHUNT_* и DUPLICATE_FINDING — гейты охоты, не общий retry

Раздел

Отказы по авторизации packet

Пример отказа
{
  "error": {
    "code": "PACKET_AUTHORIZATION_DENIED",
    "message": "Мутация packet не разрешена в текущем состоянии",
    "details": {
      "denialCode": "state_not_permitted"
    }
  }
}

Раздел

Retry flow для stale snapshot

  • Ещё раз прочитайте актуальный task или packet context.
  • Используйте свежие packetRevision, taskRevision, contractVersion и contextToken.
  • Запускайте новый осознанный retry с новым idempotency key, если операция не является безопасным replay.

Диаграмма

Recovery flow для stale context

Ошибку stale context нужно чинить обновлением snapshot, а не давлением того же payload повторно.

1

мутация отклонена

2

обнаружен stale context

3

refetch task/packet context

4

обновить CAS-поля

5

повторить со свежим idempotency key

Раздел

Ошибки багханта: код → что сделать

  • BUGHUNT_SCHEMA_INVALID (400): iteration 1–7, headCommit 40-hex, findings 0–20 с id/severity/title/status, remainingOpen = числу open, scope=packet требует packetId, quote ≥20, note ≥80.
  • BUGHUNT_INSPECTION_REQUIRED (400): code-пакет без unique focus или без inspections[]. Добавьте inspections[] по filesChanged. Это не BUGHUNT_BURST.
  • BUGHUNT_INSPECTION_PATH (400): inspection.path нет в filesChanged git-diff-summary этого пакета.
  • BUGHUNT_BURST (409): два цикла одного леджера быстрее 60с. Подождите и повторите тот же payload. Это пауза, не блокер Done.
  • BUGHUNT_FOCUS_REUSED / BUGHUNT_QUOTE_REUSED (409): возьмите другой focus из семи / другую цитату.
  • BUGHUNT_STALE_HEAD (409): прошлый цикл оставил remainingOpen>0, а вы шлёте тот же headCommit. Сначала фикс и новый коммит.
  • DUPLICATE_FINDING (409): тот же title + inspections[i].path уже есть в леджере. Позовите get_finding. Не переотправляйте со status=fixed. Тот же title в другом path — ок.
  • BUGHUNT_REQUIRED / BUGHUNT_CYCLES_INCOMPLETE (409): нет 7 циклов нужного scope. nextSafeActions: submit_bughunt_iteration. Коммент APPROVE не считается.
  • BUGHUNT_OPEN_FINDINGS (409): последняя охота текущего head ещё с remainingOpen>0. Пофиксите, закоммитьте, сдайте цикл с remainingOpen=0.
  • BUGHUNT_INSPECTION_INCOMPLETE (409): code-пакет закрывается без полного набора focus/inspections. Допишите циклы, не жмите Done.
  • NOT_FOUND (404) на get_finding: id нет на этой задаче. Не путайте packet ledger и card ledger.
  • Нет tool submit_bughunt_iteration в runtime: degraded-mode. Не выдумывайте леджер и не закрывайте карточку суррогатом.

Copy-paste охоты

Готовый payload и форма get_finding — на /docs/mcp/tools (секция Багхант) и /docs/examples. Публичный гайд: /docs/public-mcp?file=skills/execution.md §5b.

Следующие материалы

Связанные страницы

Коротко

О чём эта страница

Ошибки и troubleshooting

Типовые ошибки Treker Zadachek MCP и API: auth, stale context, packet denial и каталог BUGHUNT_* / DUPLICATE_FINDING с recovery.

FAQ

Что делать при STALE_CONTEXT?

Сделайте refetch актуального task или packet context, а затем повторите запрос осознанно с новыми revision-полями вместо слепого повтора stale-запроса.

Что обычно означает PACKET_AUTHORIZATION_DENIED?

Это означает, что запрошенная мутация packet невалидна для текущего workflow lane, состояния lease или статуса packet. Читайте denialCode и исправляйте шаг workflow вместо brute-force повтора того же вызова.

Почему 400, если remainingOpen=0, а в findings есть status=open?

remainingOpen обязан равняться числу open в этом payload. Ноль при открытых багах — BUGHUNT_SCHEMA_INVALID. Ноль нужен только на последней охоте текущего head перед release/Done.

Чем BUGHUNT_BURST отличается от BUGHUNT_INSPECTION_REQUIRED?

BURST — два цикла быстрее 60 секунд: подождите и повторите. INSPECTION_REQUIRED — code-пакет без focus/inspections. Это разные коды и разные фиксы.

В каталоге нет submit_bughunt_iteration. Можно закрыть карточку комментарием?

Нет. Это degraded-mode: полный прогон тестов + self-review в вердикте/коммитах, без выдуманного леджера. APPROVE-коммент не охота и не Done.

Источники

README MCP server

mcp-server/README.md

Главное публичное описание MCP-контракта и ожиданий к оператору.

Reference External API

docs/api/external-statistics-api.md

Семейства HTTP endpoint-ов, filters, shape ответа и примеры.

Контракт OpenAPI

docs/openapi/external-statistics-v1.yaml

Machine-readable reference для tooling и генерации клиентов.

Читать дальше