Используйте эту страницу, когда интеграция ведёт себя не так, как ожидалось, и нужен короткий путь к диагнозу.
Читайте реальную причину отказа и делайте минимальный корректный следующий шаг
Раздел
Основные семейства ошибок
- 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 повторно.
мутация отклонена
обнаружен stale context
refetch task/packet context
обновить CAS-поля
повторить со свежим 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.
Следующие материалы
Связанные страницы
Безопасность и модель доступа
Модель безопасности Treker Zadachek MCP и External API: project scope, работа с API key, token redaction и безопасное поведение оператора.
Справочник MCP tools
Справочник MCP tools Treker Zadachek: discovery, жизненный цикл work packet, progress, artifact, багхант, handoff, recovery и convergence.
Примеры
Примеры запросов для Treker Zadachek MCP и External API: ready discovery, claim, progress, artifact, багхант и handoff.
Коротко
О чём эта страница
Ошибки и 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 и генерации клиентов.
Читать дальше