Руководство по интеграции

Версия документа: для gateway 4.2.0

Аудитория: инженерные и платформенные команды, интегрирующие HiveTrace Gateway в производственную среду.

Документ описывает контракт между клиентским приложением и gateway: формат запросов и ответов, модель обработки ошибок, особенности потоковой передачи. Руководство предназначено для практического внедрения и эксплуатации интеграции.

---

1. Назначение и место в архитектуре

HiveTrace Gateway представляет собой HTTP-прокси, который размещается между клиентским приложением и LLM-провайдером (OpenAI, Anthropic, LiteLLM, vLLM, Ollama и др.). Поддерживаются два формата с полным пайплайном HiveTrace: OpenAI Chat Completions (/v1/chat/completions) и Anthropic Messages (/v1/messages). Для каждого запроса выполняется следующая последовательность:

1. Gateway принимает обычный вызов OpenAI или Anthropic SDK.
2. Регистрируется в HiveTrace до отправки в LLM.
3. Проксируется в апстрим.
4. Регистрируется в HiveTrace после получения ответа.

При соответствующей политике HiveTrace может отклонить запрос или заменить ответ модели на заранее определенное сообщение. Это возможно только при синхронном режиме доставки данных на анализ в мониторинг hivetrace.

┌────────────┐     ┌──────────────────┐     ┌────────────┐
│   Client   │────▶│  HiveTrace       │────▶│  Upstream  │
│            │     │  Gateway :4100   │     │ (LiteLLM,  │
│            │◀────│                  │◀────│  vLLM, …)  │
└────────────┘     └────────┬─────────┘     └────────────┘
                            │
                            ▼
                    ┌──────────────┐
                    │  HiveTrace   │
                    │  Monitoring  │
                    └──────────────┘

1.1. Совместимость с OpenAI

API соответствует OpenAI Chat Completions, Embeddings и Models: формат тела запроса, форма ответа, SSE-стриминг и envelope ошибок идентичны OpenAI. Тело запроса при форвардинге в апстрим не модифицируется (исключение: stream: true принудительно переписывается в false при app_mode=sync, см. раздел 6.3.2).

Дополнительные значения (application_id, user_id, session_id), необходмые для аналитики мониторинга, в gateway передаются через HTTP-заголовки. В апстрим они не пробрасываются и на ответ модели не влияют. Полный список — раздел 4.

Заголовок X-HiveTrace-Api-Key обязателен для всех запросов к gateway. В OpenAI SDK задается через default_headers — пример в разделе 5.1.

1.2. OpenAPI спецификация

Контракт API доступен в формате OpenAPI 3.1:

• На запущенном экземпляре gateway: GET /openapi.json, Swagger UI на /docs, ReDoc на /redoc.

1.3. Поддержка Anthropic API

Помимо OpenAI gateway поддерживает нативный формат Anthropic:

• POST /v1/messages — Anthropic Messages API с полным пайплайном HiveTrace (pre-call + post-call + блокировки), форма запроса и ответа идентичны Anthropic. Запрос форвардится в Anthropic-passthrough апстрима (LiteLLM /anthropic/v1/messages → api.anthropic.com); заголовки anthropic-version / anthropic-beta / x-api-key пробрасываются без изменений.
• POST|GET|DELETE /v1/files — Anthropic Files API, прозрачное проксирование (см. раздел 5.6).

Оба формата проходят через единый пайплайн HiveTrace; различается только разбор тела запроса/ответа. Извлечение идентификаторов (X-Application-Id/X-User-Id/X-Session-Id), модель ошибок и режимы доставки телеметрии — общие.

---

2. Эндпоинты

Gateway предоставляет единую точку входа (по умолчанию :4100) и реализует следующие эндпоинты:

Метод	Путь	Назначение	Пайплайн HiveTrace
POST	/v1/chat/completions	OpenAI chat completion. Для асинхронного режима мониторинга поддерживается stream: true.	Полный (pre-call + post-call + логирование ошибок)
POST	/v1/messages	Anthropic messages. Для асинхронного режима поддерживается stream: true.	Полный (pre-call + post-call + логирование ошибок)
POST	/v1/embeddings	Embeddings.	Не применяется — прозрачное проксирование
GET	/v1/models	Список моделей апстрима.	Не применяется — прозрачное проксирование
POST, GET, DELETE	/v1/files, /v1/files/{id}, /v1/files/{id}/content	Anthropic Files API (загрузка / список / метаданные / скачивание / удаление).	Не применяется — прозрачное проксирование (загрузка дополнительно зеркалируется в аудит, см. 5.6)

Полный контур проверок политиками HiveTrace доступен для /v1/chat/completions и /v1/messages.

---

3. Аутентификация

Gateway использует двухуровневую модель авторизации:

3.1. Клиент → Gateway

Клиент передает заголовок X-HiveTrace-Api-Key: <gateway-key> — обязательный ключ доступа к gateway. Без него любой запрос ко всем эндпоинтам (/v1/chat/completions, /v1/messages, /v1/embeddings, /v1/models, /v1/files) отклоняется со статусом 401 invalid_request_error. Этим же ключом gateway аутентифицируется в HiveTrace при исходящих вызовах, поэтому переключение клиентского ключа автоматически переключает идентичность gateway в HiveTrace — серверный токен в env не используется и был удалён.

3.2. Клиент → Gateway → Апстрим

Клиент передает заголовок Authorization: Bearer <key> (OpenAI) или x-api-key: <key> (Anthropic SDK). Gateway не валидирует и не сохраняет этот токен; он передается в апстрим без изменений. Это означает следующее:

• <key> должен быть действительным ключом апстрима (например, OpenAI API key для прямого обращения к OpenAI или ключ LiteLLM).
• Для Anthropic-формата Anthropic SDK отправляет ключ в x-api-key; gateway пробрасывает его (вместе с anthropic-version / anthropic-beta) в Anthropic-passthrough апстрима.

3.3. Приложения

Идентификация приложения выполняется по заголовку X-Application-Id (см. п4). Это позволяет одному экземпляру gateway обслуживать несколько приложений с различными политиками HiveTrace без изменения инфраструктурной конфигурации.

---

4. Заголовки запроса

Колонка «Источник» обозначает, относится ли заголовок к стандарту OpenAI (проксируется в апстрим без интерпретации gateway) или является расширением gateway (обрабатывается gateway, в апстрим не пробрасывается).

Заголовок	Источник	Обязательность	Назначение
Authorization: Bearer <key>	OpenAI	для апстрима	Ключ апстрима. Передаётся в апстрим без изменений и валидации.
x-api-key: <key>	Anthropic	для апстрима (Anthropic)	Ключ апстрима для Anthropic SDK. Пробрасывается без изменений.
anthropic-version, anthropic-beta	Anthropic	для Anthropic-запросов	Стандартные заголовки Anthropic (напр. anthropic-beta: files-api-2025-04-14). Пробрасываются в апстрим.
Content-Type: application/json	OpenAI	для non-stream запросов	Стандартный для OpenAI API.
Accept: text/event-stream	OpenAI	для stream-запросов	Стандартный для OpenAI streaming.
X-HiveTrace-Api-Key	Gateway	да	Ключ доступа к gateway. Также используется как Bearer в исходящих вызовах gateway → HiveTrace. Отсутствие или пустое значение → 401.
X-Application-Id	Gateway	нет	UUID приложения в HiveTrace. Определяет per-app политику. При отсутствии — fallback на ENV HIVETRACE_APPLICATION_ID.
X-User-Id	Gateway	нет	Идентификатор конечного пользователя для аудита.
X-Session-Id	Gateway	нет	Идентификатор пользовательской сессии.
X-Attached-Files	Gateway	нет	JSON-массив дескрипторов вложений для отдельной аудит-копии в HiveTrace. Формат — раздел 5.3.2.

---

5. Формат запроса

Тело запроса соответствует payload OpenAI Chat Completions / Embeddings. Специфичных для gateway полей в теле нет.

5.1. HTTP-примеры

Минимальный запрос:

curl -X POST http://gateway:4100/v1/chat/completions \
  -H "Authorization: Bearer <upstream-key>" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: 11111111-2222-3333-4444-555555555555" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

С идентификацией пользователя и сессии:

curl -X POST http://gateway:4100/v1/chat/completions \
  -H "Authorization: Bearer <upstream-key>" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: 11111111-…" \
  -H "X-User-Id: alice@company.com" \
  -H "X-Session-Id: session-2025-04-28-abc" \
  -d '{ "model": "gpt-5", "messages": [...] }'

Streaming:

curl -X POST http://gateway:4100/v1/chat/completions \
  -H "Authorization: Bearer <upstream-key>" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "model": "gpt-5", "stream": true, "messages": [...] }'

5.3. Передача файлов

Передача файлов поддерживается двумя стратегиями. Они решают разные задачи и могут использоваться по отдельности или одновременно.

Стратегия	Файл попадает в LLM	Файл попадает в HiveTrace (audit)	Изменения в OpenAI-клиенте
5.3.1. Стандарт OpenAI (multimodal)	Да	Нет	Не требуются
5.3.2. Заголовок X-Attached-Files	Нет	Да	Один дополнительный заголовок
5.3.3. Обе стратегии в одном запросе	Да	Да	Один дополнительный заголовок

5.3.1. Стратегия 1 — стандарт OpenAI (multimodal messages[].content)

Файлы передаются стандартным OpenAI-способом — массивом частей в messages[].content. Gateway не интерпретирует эти части и форвардит тело запроса в апстрим без изменений.

curl -X POST http://gateway:4100/v1/chat/completions \
  -H "Authorization: Bearer <upstream-key>" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: <APPLICATION_ID>" \
  -d '{
    "model": "gpt-5",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Что на изображении?"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KG..."}}
      ]
    }]
  }'

Поведение:

• LLM. Получает запрос в стандартном OpenAI multimodal формате. Обработка image_url, file и прочих нетекстовых частей зависит от модели и апстрима.
• HiveTrace. В запись user_prompt записывается только текстовая часть (type: "text"). Содержимое image_url, file и прочих нетекстовых частей в HiveTrace не сохраняется.
• Изменения в клиенте. Не требуются. Любой OpenAI-клиент или SDK с поддержкой multimodal работает без изменений.

Применимо, когда требуется обработка файла моделью без сохранения аудит-копии файла в HiveTrace.

5.3.2. Стратегия 2 — расширение X-Attached-Files

Файлы передаются в заголовке X-Attached-Files как JSON-массив дескрипторов. Gateway не пробрасывает заголовок в апстрим; вместо этого он скачивает / декодирует файлы и прикрепляет их к аудит-записи user_prompt в HiveTrace.

Передача через base64 (для локальных файлов):

B64=$(base64 -i ./test111.txt | tr -d '\n')
curl -X POST http://gateway:4100/v1/chat/completions \
  -H "Authorization: Bearer <upstream-key>" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: <APPLICATION_ID>" \
  -H "X-User-Id: alice@company.com" \
  -H "X-Attached-Files: [{\"name\":\"test111.txt\",\"content_base64\":\"$B64\",\"type\":\"text/plain\"}]" \
  -d '{ "model": "gpt-5", "messages": [{"role":"user","content":"Сообщение пользователя"}] }'

Передача через URL (gateway скачивает файл по HTTP/HTTPS):

curl -X POST http://gateway:4100/v1/chat/completions \
  -H "Authorization: Bearer <upstream-key>" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: <APPLICATION_ID>" \
  -H "X-User-Id: alice@company.com" \
  -H 'X-Attached-Files: [{"url":"https://files.company.example/contract.pdf","name":"contract.pdf","type":"application/pdf"}]' \
  -d '{ "model": "gpt-5", "messages": [{"role":"user","content":"Сообщение пользователя"}] }'

Формат дескриптора (X-Attached-Files — JSON-массив, элементы содержат либо url, либо content_base64):

Поле	Тип	Описание
url	string	HTTP/HTTPS URL файла. Поддерживается также data: URI с inline base64.
content_base64	string	Base64-кодированное содержимое файла. Альтернатива url.
name	string	Имя файла. Используется при сохранении в HiveTrace; при отсутствии выводится из URL.
type	string	MIME-тип файла. При отсутствии определяется по расширению или Content-Type ответа при скачивании.

Алиас заголовка: X-AttachedFiles.

Поведение:

• LLM. Тело запроса в апстрим уходит без изменений; X-Attached-Files в апстрим не пробрасывается. Если в messages[].content нет inline-данных файла — модель его не получает.
• HiveTrace. В запись user_prompt дополнительно прикрепляется аудит-копия файла, привязанная к analysis_id запроса.
• Изменения в клиенте. Один дополнительный заголовок. Тело запроса остаётся стандартным OpenAI-payload.

Дополнительные возможности по сравнению со стратегией 1:

• Аудит-копия файла сохраняется в HiveTrace независимо от того, передаётся ли файл модели.
• Поддерживается передача по URL — gateway сам скачивает файл; клиенту не нужно загружать содержимое в payload запроса.
• Содержимое файла попадает в HiveTrace целиком, а не только текстовая часть запроса.

5.3.3. Комбинированный сценарий

Если требуется одновременно (а) подать файл в LLM и (б) сохранить его аудит-копию в HiveTrace, обе стратегии применяются в одном запросе. messages[].content обеспечивает доставку в модель, X-Attached-Files — аудит-копию в HiveTrace.

B64=$(base64 -i ./contract.pdf | tr -d '\n')
curl -X POST http://gateway:4100/v1/chat/completions \
  -H "Authorization: Bearer <upstream-key>" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: <APPLICATION_ID>" \
  -H "X-User-Id: alice@company.com" \
  -H "X-Attached-Files: [{\"name\":\"contract.pdf\",\"content_base64\":\"$B64\",\"type\":\"application/pdf\"}]" \
  -d "{
    \"model\": \"gpt-5\",
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        {\"type\": \"text\", \"text\": \"Сделай выжимку документа.\"},
        {\"type\": \"file\", \"file\": {\"filename\": \"contract.pdf\", \"file_data\": \"data:application/pdf;base64,$B64\"}}
      ]
    }]
  }"

В этом случае:

1. messages[].content пропускается в апстрим без изменений; модель получает файл по стандартному OpenAI-протоколу.
2. X-Attached-Files обрабатывается gateway параллельно: файл декодируется и прикрепляется к user_prompt в HiveTrace.
3. Ответ модели регистрируется в HiveTrace стандартным post-call вызовом.

Применимо для compliance-сценариев, где требуется и обработка файла моделью, и аудит исходного содержимого в HiveTrace.

5.3.4. Обработка ошибок при работе с вложениями

Сбой скачивания или декодирования файла (HTTP >=400, таймаут, размер превышает HIVETRACE_FILES_MAX_BYTES, ошибка декодирования base64) не приводит к отказу клиенту. Gateway изолирует такие сбои:

• Проблемный файл не попадает в HiveTrace. В логи gateway пишется предупреждение с диагностикой (Attachment download failed: url=… status=404 и т. п.).
• Остальные файлы в X-Attached-Files обрабатываются независимо.
• Тело запроса передаётся в апстрим без изменений.
• Клиент получает обычный ответ модели с HTTP-статусом, соответствующим ответу апстрима.

Лимиты на вложения

Параметр	Дефолт	ENV
Максимальный размер одного файла	20 MiB	HIVETRACE_FILES_MAX_BYTES
Параллельных скачиваний	4	HIVETRACE_FILES_MAX_CONCURRENCY
Таймаут скачивания одного файла	60 с	HIVETRACE_FILES_TIMEOUT

Файл, превышающий лимит, исключается из обработки с записью предупреждения в лог; остальные вложения продолжают обрабатываться.

5.4. Лимиты на размер тела запроса

Gateway не накладывает собственный лимит на размер тела запроса. Контроль выполняется на стороне апстрима.

5.5. Anthropic Messages API (/v1/messages)

Тело запроса соответствует payload Anthropic Messages (model, max_tokens, system, messages[] с блоками content). Специфичных для gateway полей в теле нет; идентификаторы передаются теми же заголовками, что и для OpenAI (раздел 4).

curl -X POST http://gateway:4100/v1/messages \
  -H "x-api-key: <upstream-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: 11111111-…" \
  -H "X-User-Id: alice@company.com" \
  -H "X-Session-Id: session-2025-04-28-abc" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

Для Anthropic SDK gateway задаётся через base_url, а ключ доступа к gateway — через default_headers:

import anthropic

client = anthropic.Anthropic(
    base_url="http://gateway:4100",
    api_key="<upstream-key>",                 # → x-api-key, пробрасывается в апстрим
    default_headers={
        "X-HiveTrace-Api-Key": "<gateway-key>",
        "X-Application-Id": "11111111-…",
        "X-User-Id": "alice@company.com",
        "X-Session-Id": "session-2025-04-28-abc",
    },
)
client.messages.create(
    model="claude-sonnet-4-6", max_tokens=1024,
    messages=[{"role": "user", "content": "Привет!"}],
)

Поведение:

• LLM. Тело форвардится в Anthropic-passthrough апстрима без изменений (исключение: stream: true → false при app_mode=sync, см. 6.3.2).
• HiveTrace. В user_prompt записывается текст из text-блоков последнего сообщения user; в llm_answer — текст из text-блоков ответа. Файлы, переданные блоком document/image (base64) или ссылкой file_id, прикрепляются к аудит-записи (раздел 5.6).
• Стриминг (stream: true) поддерживается в асинхронном режиме; формат SSE — нативный Anthropic (раздел 6.4).

5.6. Anthropic Files API (/v1/files)

Прозрачное проксирование Anthropic Files API в апстрим (LiteLLM /anthropic/v1/files → api.anthropic.com). Пайплайн guardrail не применяется. Загрузка идёт multipart/form-data, скачивание возвращает бинарный поток.

# Загрузка файла (Anthropic SDK выставляет anthropic-beta автоматически)
curl -X POST http://gateway:4100/v1/files \
  -H "x-api-key: <upstream-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "X-HiveTrace-Api-Key: <gateway-key>" \
  -F "file=@report.pdf;type=application/pdf"
# → {"id": "file_…", "type": "file", …}

# Скачивание (только артефакты skills / code execution; загруженные файлы Anthropic скачивать не даёт)
curl http://gateway:4100/v1/files/<file_id>/content \
  -H "x-api-key: <upstream-key>" -H "X-HiveTrace-Api-Key: <gateway-key>" -o out.bin

Загруженный file_id затем указывается в /v1/messages блоком document:

{"type": "document", "source": {"type": "file", "file_id": "file_…"}}

Зеркалирование в аудит HiveTrace (паритет со стратегией X-Attached-Files OpenAI-пути):

• При загрузке через /v1/files gateway сохраняет содержимое в кэше file_id → bytes (Redis).
• Когда /v1/messages ссылается на этот file_id, gateway достаёт байты из кэша и прикрепляет файл к user_prompt. Inline base64-блоки прикрепляются напрямую, без кэша.
• Требуется Redis (GATEWAY_REDIS_URL или REDIS_*). Без Redis загрузка и сам запрос работают, но файлы по file_id в аудит не попадают (base64-блоки — попадают). TTL кэша — HIVETRACE_FILES_CACHE_TTL_SECONDS (раздел 9), размер — HIVETRACE_FILES_MAX_BYTES.

---

6. Формат ответа

6.1. Успешный non-streaming ответ

Тело ответа и HTTP-статус полностью соответствуют ответу апстрима. Тип содержимого: application/json. Структура соответствует стандартному формату OpenAI:

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 23, "completion_tokens": 45, "total_tokens": 68}
}

6.2. Успешный streaming ответ

Content-Type: text/event-stream. Тело ответа представляет собой последовательность SSE-кадров:

data: {"id":"…","object":"chat.completion.chunk","choices":[{"delta":{"content":"При"}}]}

data: {"id":"…","object":"chat.completion.chunk","choices":[{"delta":{"content":"вет!"},"finish_reason":"stop"}]}

data: [DONE]

Между обычными data:-кадрами могут передаваться comment-кадры для поддержания соединения:

: keepalive

Streaming ответ может формироваться для пользователя при работающем мониторинге только в асинхронном режиме.

6.3. Подмена ответа политикой HiveTrace

Возможна только при app_mode=sync в per-app политике (Redis). Если mode=async либо политика не настроена, описанное в этом разделе поведение к запросу не применяется.

6.3.1. Pre-call блок (HiveTrace отверг до вызова LLM)

Запрос не был передан в апстрим. Gateway возвращает синтезированный chat.completion с диагностическим блоком metadata.hivetrace:

{
  "id": "hivetrace-guardrails-<uuid>",
  "object": "chat.completion",
  "created": 1717171717,
  "model": "<запрошенная или 'unknown'>",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "<фраза из политики приложения>"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
  "metadata": {
    "hivetrace": {
      "response_replaced": true,
      "response_replacement": {
        "stage": "pre_call",
        "type": "<guardrails|custom_policy|dataclean>",
        "request_id": "<metadata.request_id из тела запроса или сгенерированный UUID>"
      },
      "prepared_response": { "...": "контекст вердикта от HiveTrace" }
    }
  }
}

Клиент может определить факт замены по наличию metadata.hivetrace.response_replaced == true либо по префиксу id (hivetrace-…).

6.3.2. Streaming + sync mode

В режиме sync gateway принудительно отключает stream: true (заменяя его на stream: false) еще до обращения к HiveTrace. Причина заключается в том, что подмена SSE-ответа после начала передачи клиенту технически невозможна. Поэтому в sync-режиме клиент всегда получает non-streaming ответ, даже если в body.stream было указано true. Это справедливо и для /v1/messages.

6.4. Формат ответа Anthropic (/v1/messages)

Тело ответа и HTTP-статус полностью соответствуют ответу Anthropic-апстрима.

Non-streaming — application/json, нативная форма Anthropic message:

{
  "id": "msg_…",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [{"type": "text", "text": "..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 23, "output_tokens": 45}
}

Streaming — text/event-stream, нативная последовательность событий Anthropic (типизированные event:-кадры, без терминатора data: [DONE]):

event: message_start
data: {"type":"message_start","message":{"id":"msg_…", …}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"При"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":7}}

event: message_stop
data: {"type":"message_stop"}

Между кадрами так же могут передаваться comment-кадры : keepalive для поддержания соединения.

Подмена ответа политикой (app_mode=sync, аналогично разделу 6.3) для /v1/messages синтезируется в форме Anthropic message:

{
  "id": "hivetrace-guardrails-<uuid>",
  "type": "message",
  "role": "assistant",
  "model": "<запрошенная или 'unknown'>",
  "content": [{"type": "text", "text": "<фраза из политики приложения>"}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 0, "output_tokens": 0},
  "metadata": {"hivetrace": {"response_replaced": true, "response_replacement": {"stage": "pre_call", "type": "guardrails", "request_id": "…"}}}
}

Факт замены определяется по metadata.hivetrace.response_replaced == true или по префиксу id (hivetrace-…).

---

7. Ошибки

Все ошибки, возвращаемые клиенту, имеют следующую форму:

{"error": {"message": "...", "type": "...", "code": <int>}}

Если апстрим уже возвращает ошибку в формате OpenAI ({"error": {...}}), gateway передает ее без дополнительной обертки, сохраняя исходные поля провайдера (type, param, code).

Поле type используется для различения источников ошибок:

• invalid_request_error — клиентская ошибка, отклонённая gateway или апстримом.
• upstream_error — апстрим вернул >=400, а тело ответа не соответствовало OpenAI-совместимому формату.
• gateway_error — gateway не смог успешно обратиться к апстриму. Всегда code: 502.
• rate_limit_error, authentication_error и др. — нативные значения от OpenAI-совместимых апстримов, передаваемые без изменения.

7.1. Полная таблица

Статус	Источник	Условие	Тип в error.type
400	gateway	Невалидный JSON в теле запроса	invalid_request_error
400	апстрим	Бизнес-валидация (отсутствует messages, превышен context window, и т.п.)	invalid_request_error (passthrough)
401	gateway	Отсутствует или пустой заголовок X-HiveTrace-Api-Key	invalid_request_error
401	апстрим	Authorization: Bearer отвергнут апстримом	invalid_request_error (passthrough)
403	апстрим	Авторизация прошла, но действие запрещено (например, organization without quota)	passthrough
404	апстрим	Указанная модель не существует	invalid_request_error (passthrough)
413	апстрим / прокси	Тело слишком большое	upstream_error
422	апстрим	Payload не прошел валидацию (strict-mode схемы)	passthrough
429	апстрим	Rate limit	rate_limit_error (passthrough)
500	апстрим	Внутренняя ошибка апстрима	upstream_error
502	gateway	Сетевая ошибка между gateway и апстримом (DNS, refused, TLS). Также — httpx.ReadTimeout ДО первого байта на non-streaming запросе.	gateway_error
503	апстрим	Апстрим недоступен (maintenance, перегруз)	upstream_error
504	— (только в SSE error-кадрах)	mid-stream httpx.TimeoutException	upstream_error

---

8. Таймауты и лимиты

8.1. Таймауты по слоям

Слой	Параметр	Дефолт	Кто контролирует
Gateway → апстрим (один HTTP-вызов)	GATEWAY_UPSTREAM_TIMEOUT	120 с	gateway
Gateway → HiveTrace (/process_request/, /process_response/)	HIVETRACE_TIMEOUT	60 с	gateway
Gateway → URL вложения (скачивание)	HIVETRACE_FILES_TIMEOUT	60 с	gateway
Gateway → клиент: SSE keepalive	GATEWAY_STREAM_HEARTBEAT_SECONDS	60 с	gateway

---

9. Конфигурация

9.1. Минимальный набор переменных окружения

# Апстрим
UPSTREAM_URL=http://litellm:4000
# Префикс Anthropic-passthrough на апстриме (для /v1/messages и /v1/files)
ANTHROPIC_PASSTHROUGH_PREFIX=/anthropic/v1

# HiveTrace
HIVETRACE_URL=https://hivetrace.example.com/api
HIVETRACE_APPLICATION_ID=<default app uuid>
# TTL кэша file_id→bytes для зеркалирования файлов в аудит (0 — отключить)
HIVETRACE_FILES_CACHE_TTL_SECONDS=86400

# Redis (per-app политики + кэш file_id→bytes для аудита Anthropic-файлов;
# опционально, если блокировки и аудит файлов по file_id не требуются)
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
REDIS_USER=""
REDIS_PASSWORD="admin"
REDIS_SSL=False

9.2. Поведение при отсутствии HiveTrace

Если HIVETRACE_URL не задан, gateway форвардит запросы в апстрим без отправки телеметрии в HiveTrace. При импорте модуля в stderr выводится предупреждение HiveTrace is effectively disabled.

Контракт X-HiveTrace-Api-Key сохраняется: ключ остается обязательным для клиентских запросов, однако при отсутствии подключения к HiveTrace фактически не используется. Этот режим предназначен для отладки и устойчивой обработки ошибок конфигурации; в развертывании параметр HIVETRACE_URL должен быть задан явно.

9.3. Поведение при отсутствии Redis

Если Redis не сконфигурирован, per-app политики блокировки недоступны; pre-call и post-call телеметрия в HiveTrace отправляется в режиме async по умолчанию. Дополнительно становится недоступно зеркалирование Anthropic-файлов по file_id в аудит (раздел 5.6): загрузка и сами запросы работают, но в аудит попадают только inline base64-вложения.