Request ID при ошибке AI API: как диагностировать запрос без утечки данных

Что request ID даёт, а чего не даёт

Request ID связывает технические события одной попытки: вход на ваш backend, исходящий запрос, ответ и запись метрики. Он не является паролем, доказательством личности или универсальным ключом к данным. Если внешний сервис присылает идентификатор в заголовке или теле, сначала проверьте его название и договорённый формат в актуальной документации. Если не присылает, создавайте собственный UUID на границе приложения и передавайте его в структурированную телеметрию.

Полезная запись содержит время в UTC, внутренний request ID, версию маршрута, выбранный model ID, HTTP-класс, длительность и безопасное состояние retry. Она не должна содержать Bearer-токен, cookie, исходный prompt, полный ответ, изображения пользователей или приватные URL. При расследовании один идентификатор лучше огромного скриншота консоли: он позволяет ограничить доступ к данным и не вынуждает разработчика копировать секрет в тикет.

Сначала классифицируйте ответ

Разделите ошибки на понятные группы. Ошибка валидации 400 или 422 обычно означает, что ваш маршрут должен проверить типы, обязательные поля или разрешённый model ID до вызова. 401 или 403 не нужно расшифровывать пользователю как состояние ключа: проверьте серверную конфигурацию, проект и права в закрытом контуре. 429 требует ограниченной очереди или backoff, а не параллельной волны повторов. 5xx и сетевой timeout требуют статуса «временно недоступно» и контролируемой проверки.

Один и тот же request ID не делает причины одинаковыми. Сохраняйте класс и безопасный код вашей ошибки, чтобы frontend знал, можно ли предложить повтор или следует исправить ввод. Подробные разборы есть в статьях о 400 и 422, о 401 и 403 и о 429 и backoff. Внешние сообщения об ошибке не вставляйте в HTML пользователя без экранирования и без проверки на лишние данные.

Добавьте безопасную корреляцию в Node.js

Пример ниже запускается в Node.js 18+ и показывает минимальную обёртку исходящего вызова. Она создаёт внутренний ID, передаёт только безопасный заголовок корреляции в собственный лог и возвращает клиенту нейтральную ошибку. Поле x-request-id в ответе gateway трактуется как необязательное: используйте его, только если ваш текущий контракт действительно его документирует. Никогда не отправляйте RUSSIAAPI_API_KEY в логи.

import { randomUUID } from 'node:crypto';

export async function callAssistant(input, logger) {
  const requestId = randomUUID();
  const startedAt = Date.now();
  const response = await fetch('https://russiaapi.com/v1/chat/completions', {
    method: 'POST',
    headers: { authorization: `Bearer ${process.env.RUSSIAAPI_API_KEY}`, 'content-type': 'application/json' },
    body: JSON.stringify({ model: process.env.RUSSIAAPI_TEXT_MODEL, messages: [{ role: 'user', content: input.message }] }),
    signal: AbortSignal.timeout(12_000)
  });
  logger.info({ requestId, status: response.status, durationMs: Date.now() - startedAt }, 'AI API call');
  if (!response.ok) return { status: 503, body: { error: 'assistant_unavailable', requestId } };
  const data = await response.json();
  return { status: 200, body: { requestId, text: data.choices?.[0]?.message?.content ?? '' } };
}

В production подключите свой logger с redaction, проверку пользователя, лимит размера сообщения и политику доступа к журналам. Ошибка клиента должна содержать только внутренний ID и статус, достаточный для поддержки. Если требуется найти один запрос, сотрудник использует этот ID в защищённой системе, а не просит прислать network export или скопировать секрет в чат.

Свяжите трассировку с наблюдаемостью

Метрики без контекста не отвечают на вопрос, какой выпуск стал хуже, а подробные логи без ограничения доступа опасны. Компромисс — агрегаты по маршруту, версии конфигурации, model ID, классу ответа и времени, плюс короткий внутренний ID для исключений. Свяжите ID в вашем gateway, очереди и callback-обработчике, но не передавайте его как разрешение на скачивание результата. Для распределённой телеметрии можно использовать совместимый с вашей инфраструктурой trace ID, если он не включает данные пользователя.

Регулярно тестируйте, что redaction работает: лог искусственного Bearer-токена должен быть замаскирован, а вложенные поля входа — исключены. Укажите срок хранения, владельца и роль, которая имеет право открывать трассировку. Практика измерения latency и статусов дополняется материалом об OpenTelemetry для LLM API; она не отменяет минимизацию данных и внутренние правила доступа.

Подготовьте безопасный пакет для поддержки

Если проблема воспроизводится, передайте время с часовым поясом, URL вашего маршрута без query с секретами, внутренний request ID, HTTP-класс, версию приложения и краткое описание ожидаемого результата. Этого достаточно, чтобы начать поиск. При необходимости приложите минимальный синтетический payload, созданный специально для диагностики, а не запись настоящего пользователя. Укажите, выполнялся ли retry и был ли запрос отменён клиентом.

Не передавайте ключи RussiaAPI, ключи вышестоящих провайдеров, cookie, пароли, коды подтверждения, полные заголовки или приватные исходные материалы. Поддержка не должна просить такие значения для обычной проверки статуса. Если в ошибке видны личные данные или секрет, сначала отзовите или ротируйте скомпрометированный секрет по вашему процессу, затем ограничьте доступ к логу и зафиксируйте инцидент.

Чек-лист диагностики

1. Каждый серверный вызов имеет внутренний request ID, а журнал содержит только безопасные метаданные.
2. HTTP-ответ классифицирован: валидация, доступ, лимит, временный сбой или неопределённый timeout.
3. Логгер маскирует Authorization и не пишет prompt, cookie, приватные URL или персональные поля.
4. Клиент получает нейтральную ошибку и внутренний ID, но не ответ поставщика.
5. Поддержка получает время, маршрут и ID; ей не нужны API-ключи или network export.

После исправления повторите синтетический тест и проверьте, что новый request ID появляется по всей вашей трассировке. Не используйте ID как способ обойти доступ к данным, лимиты или условия сервиса.

FAQ

Читайте также

• Логирование без утечек
• 429 и ограниченный retry
• OpenTelemetry для LLM API
• Документы RussiaAPI