Ошибки

Готово

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

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

TaskTracker намеренно сохраняет structured error code, потому что это операционно полезно для supervised systems.

Правильная реакция на stale context - refresh и retry, а не слепое повторение.

Правильная реакция на authorization denial - исправить workflow lane или scope, а не давить тем же запросом сильнее.

Раздел

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

AUTH_REQUIRED, INVALID_API_KEY, API_KEY_EXPIRED
ACCESS_DENIED
VALIDATION_ERROR
PACKET_AUTHORIZATION_DENIED с denialCode
STALE_CONTEXT и REVISION_MISMATCH с retry hint

Раздел

Отказы по авторизации 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 повторно.

mutation denied

↓

stale context detected

↓

refetch task or packet context

↓

refresh CAS fields

↓

retry with fresh idempotency key

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

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

Безопасность и модель доступа

Готово

Модель безопасности TaskTracker MCP и External API: project scope, работа с API key, token redaction и безопасное поведение оператора.

Справочник MCP tools

Готово

Справочник по TaskTracker MCP tools: discovery, lifecycle work packet, progress, artifact, handoff, recovery и convergence.

Примеры

Готово

Примеры запросов для TaskTracker MCP и External API: ready discovery, claim, progress, artifact и handoff.

Коротко по странице

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

Ошибки и troubleshooting

Типовые ошибки TaskTracker MCP и API: проблемы auth, отказы доступа, stale context и packet authorization denial.

FAQ

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

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

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

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

Где смотреть детали

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 и генерации клиентов.

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

Примеры

Changelog по API и MCP