Request ID

Lưu mã truy vết yêu cầu từ Header phản hồi hoặc thông tin lỗi và chuẩn bị dữ liệu giúp xác định sự cố.

Vì sao cần lưu Request ID

Request ID liên kết một yêu cầu API với bản ghi xử lý của nền tảng. Khi gặp thất bại, kết quả bất thường, hết thời gian chờ hoặc thắc mắc về phí, lưu Request ID giúp giảm nhu cầu gửi toàn bộ body và xác định đúng yêu cầu.

Tên Header trả về có thể khác nhau theo giao thức, API hoặc đường dẫn gateway. Khi kiểm tra Header phản hồi, lần lượt tìm:

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

Theo phản hồi thực tế

Không phải mọi API hoặc phản hồi đều trả tất cả Header. Chỉ cần lưu Request ID thực sự có; một số phản hồi lỗi có thể chứa Request ID trong nội dung lỗi.

Xem Header phản hồi bằng cURL

Thiết lập Base URL của trang hiện tại và API Key trong terminal đáng tin cậy trước. -i xuất cả Header và body phản hồ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":"Xin chào"}]}'

Không gửi trực tiếp lịch sử terminal hoặc ảnh chụp chứa đầy đủ Authorization cho người khác.

Đọc bằng 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": "Xin chào"}],
    },
    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)

Mã production cần giới hạn độ dài body phản hồi trong nhật ký và che thông tin nhạy cảm trong Prompt, nội dung tệp và dữ liệu người dùng.

Đọc bằng 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: 'Xin chào' }],
  }),
});

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 });

Ví dụ này chỉ dành cho môi trường máy chủ. Trình duyệt không được giữ API Key dài hạn.

Thông tin cần cung cấp khi báo sự cố

Thông tin	Ví dụ	Bắt buộc hay không
Request ID	`REQUEST_ID`	Cung cấp nếu phản hồi có
Thời gian yêu cầu	`2026-08-19 14:30 +08:00`	Có
Method / Path	`POST /v1/chat/completions`	Có
ID mô hình	Điền chính xác sau khi che thông tin nhạy cảm	Có
HTTP Status	`429`	Có
Mã lỗi và thông báo ngắn	Loại bỏ nội dung nhạy cảm	Khuyến nghị
SDK và phiên bản	Phiên bản SDK `openai`	Cung cấp khi dùng SDK

Không cung cấp API Key đầy đủ, Header xác thực, thông tin riêng tư của người dùng, tệp chưa che dữ liệu nhạy cảm hoặc toàn bộ yêu cầu và phản hồi. Request ID không phải API Key nhưng vẫn chỉ nên cung cấp khi cần khắc phục sự cố.

Làm gì khi không có Request ID

Vẫn lưu thời gian yêu cầu, endpoint, mô hình, trạng thái và body lỗi;
Kiểm tra proxy, CDN hoặc SDK không loại bỏ Header phản hồi;
Với yêu cầu theo luồng, ghi cả thời gian thiết lập và ngắt kết nối;
Với tác vụ bất đồng bộ, lưu thêm Task ID;
Khi báo sự cố, nêu rõ không tìm thấy mã truy vết trong cả Header phản hồi và nội dung lỗi.

Trang liên quan:Lỗi và khắc phục sự cố · FAQ · Quy ước chung