Request ID

Сохраняйте идентификатор запроса из заголовков или ошибки и готовьте сведения для диагностики.

Зачем сохранять Request ID

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

Имена Header могут различаться между протоколами, интерфейсами и шлюзами. Проверяйте заголовки ответа в следующем порядке:

x-request-id: REQUEST_ID
request-id: REQUEST_ID
x-oneapi-request-id: REQUEST_ID

Ориентируйтесь на фактический ответ

Не каждый интерфейс или ответ содержит все Header. Сохраните имеющийся Request ID. Некоторые ошибки также содержат Request ID в теле.

Заголовки ответа через cURL

Сначала задайте Base URL текущего сайта и API Key в доверенном терминале. -i выводит одновременно заголовки и тело:

export AGTCLOUD_BASE_URL='https://api.agtcloud.cn/v1'
export AGTCLOUD_API_KEY='your-api-key'

curl -i "${AGTCLOUD_BASE_URL:?}/chat/completions" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGTCLOUD_API_KEY:?}" \
  --data '{"model":"MODEL_ID","messages":[{"role":"user","content":"Здравствуйте"}]}'

Не отправляйте другим историю терминала или снимки, содержащие полный Authorization.

Чтение через Python

import os
import requests

base_url = os.environ["AGTCLOUD_BASE_URL"]
api_key = os.environ["AGTCLOUD_API_KEY"]

response = requests.post(
    f"{base_url}/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "MODEL_ID",
        "messages": [{"role": "user", "content": "Здравствуйте"}],
    },
    timeout=60,
)

request_id_headers = (
    "x-request-id",
    "request-id",
    "x-oneapi-request-id",
)
request_id = next(
    (response.headers.get(name) for name in request_id_headers if response.headers.get(name)),
    None,
)
print("request_id:", request_id)
print("status:", response.status_code)

В рабочем коде ограничивайте длину тела ответа в журналах и обезличивайте Prompt, содержимое файлов и данные пользователей.

Чтение через JavaScript

const response = await fetch(`${process.env.AGTCLOUD_BASE_URL}/chat/completions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGTCLOUD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'MODEL_ID',
    messages: [{ role: 'user', content: 'Здравствуйте' }],
  }),
});

const requestIdHeaderNames = [
  'x-request-id',
  'request-id',
  'x-oneapi-request-id',
] as const;
const requestId =
  requestIdHeaderNames
    .map((name) => response.headers.get(name))
    .find((value) => value !== null) ?? null;

console.log({ requestId, status: response.status });

Пример предназначен только для сервера. Не храните долгосрочный API Key в браузере.

Что предоставить при диагностике

Сведения	Пример	Обязательно
Request ID	`REQUEST_ID`	Если присутствует в ответе
Время запроса	`2026-08-19 14:30 +08:00`	Да
Method / Path	`POST /v1/chat/completions`	Да
ID модели	Укажите точно после обезличивания	Да
HTTP Status	`429`	Да
Код и краткое сообщение	Удалите чувствительные данные	Рекомендуется
SDK и версия	Версия SDK `openai`	При использовании SDK

Не предоставляйте полный API Key, Header аутентификации, личные данные, необезличенные файлы или полный запрос и ответ. Request ID — не API Key, но сообщать его следует лишь для необходимой диагностики.

Если Request ID отсутствует

Всё равно сохраните время, Endpoint, модель, статус и тело ошибки;
проверьте, не отбросили ли Header прокси, CDN или SDK;
для Streaming сохраните время подключения и разрыва;
для асинхронной задачи сохраните Task ID;
при передаче диагностики укажите, что идентификатор не найден ни в заголовках, ни в теле ошибки.

Связанные страницы: Ошибки и диагностика · FAQ · Общие соглашения