Request ID

응답 헤더나 오류 정보의 요청 추적 ID를 보관하고 원인을 찾을 수 있는 진단 정보를 준비합니다.

Request ID를 보관하는 이유

Request ID는 API 요청과 플랫폼 처리 기록을 연결합니다. 실패, 비정상 결과, 시간 초과 또는 요금 관련 문의가 발생했을 때 Request ID를 보관하면 전체 요청 본문의 전달을 줄이고 해당 요청을 찾는 데 도움이 됩니다.

프로토콜, API 또는 게이트웨이 경로에 따라 Header 이름이 다를 수 있습니다. 응답 헤더에서 다음을 차례로 확인합니다:

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

실제 응답을 기준으로 합니다

모든 API나 응답이 모든 Header를 반환하지는 않습니다. 실제 존재하는 Request ID만 보관하면 됩니다. 일부 오류 응답은 본문에도 Request ID를 포함할 수 있습니다.

cURL로 응답 헤더 확인

먼저 신뢰할 수 있는 터미널 환경에서 현재 사이트의 Base URL과 API 키를 설정합니다. -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 키를 보관해서는 안 됩니다.

문의 시 제공할 진단 정보

정보	예시	필수 여부
Request ID	`REQUEST_ID`	응답에 있으면 제공
요청 시간	`2026-08-19 14:30 +08:00`	예
Method / Path	`POST /v1/chat/completions`	예
모델 ID	민감 정보를 제거한 후 정확히 기재	예
HTTP Status	`429`	예
오류 코드와 짧은 메시지	민감한 내용 제거	권장
SDK 및 버전	`openai` SDK 버전	SDK 사용 시 제공

전체 API 키, 인증 Header, 개인정보, 마스킹하지 않은 파일 또는 전체 요청과 응답을 제공해서는 안 됩니다. Request ID는 API 키가 아니지만 필요한 문제 해결 상황에만 제공해야 합니다.

Request ID가 없는 경우

요청 시간, 엔드포인트, 모델, 상태 및 오류 본문을 보관합니다;
프록시, CDN 또는 SDK가 응답 헤더를 누락하지 않았는지 확인합니다;
스트리밍 요청은 연결 및 종료 시간도 함께 기록합니다;
비동기 작업은 Task ID도 함께 보관합니다;
문의 시 응답 헤더와 오류 본문 모두에서 추적 ID를 찾지 못했음을 설명합니다.

관련 페이지: 오류 및 문제 해결 · FAQ · 공통 규칙