작성자 주: APIYI Request ID 조회 문서가 업그레이드되었어요. 이 글에서는 오류가 났을 때 어느 문자열을 복사해야 하는지, 어떤 ID는 쓰면 안 되는지, 비동기 영상 task_id는 어떻게 저장해야 하는지, 그리고 로그에서 찾을 수 없을 때 어떤 자료를 보충해야 하는지를 정리해요.
호출 오류 후 티켓을 올릴 때, 개발자들이 흔히 같은 지점에서 막혀요. 손에 분명히 ID 문자열이 있는데 고객 지원 쪽에서 로그로 검색하지 못하는 거예요. 원인은 보통 APIYI 자체의 X-Shellapi-Request-Id가 아니라 상위 원본 벤더의 X-Request-Id를 복사했기 때문이에요. 새 문서는 바로 이 문제를 풀기 위해 다시 쓰였고, 주소는 docs.apiyi.com/faq/request-id-troubleshooting예요.
이건 껍데기만 바꾼 문서 업데이트가 아니에요. 예전 버전은 “응답 헤더”부터 설명을 시작했고, 온통 “보통”, “아마” 같은 표현뿐이라 다 읽고 나도 어디서 복사해야 하는지 알 수 없었어요. 새 버전은 순서를 뒤집었어요. 먼저 답을 주고, 그다음 가져오는 방법을, 마지막으로 티켓 템플릿을 알려줘요.
핵심 가치: 이 글을 다 읽으면 10초 안에 올바른 Request ID를 얻을 수 있고, 어떤 ID가 잘못된 것인지도 구분할 수 있어요. 로그에서 기록이 조회되지 않을 때 어떤 자료를 보충해야 하는지도 알게 돼요.

APIYI Request ID 문서, 무엇이 업그레이드되었나요
새 문서의 첫 문장이 바로 답이에요: APIYI 의 Request ID 는 응답 헤더에 있는 X-Shellapi-Request-Id 이고, 오류가 발생하면 오류 메시지 끝에도 같은 값이 붙어요. 예전 페이지에는 x-request-id 를 “문제 해결을 위해 기록해 두자”는 식으로 설명한 부분이 몇 군데 있었는데, 이번에 함께 바로잡았어요.
| 항목 | 내용 |
|---|---|
| 업데이트 시간 | 2026-11-16 |
| 문서 위치 | FAQ 카테고리 「Request ID 문제 해결」 새 페이지 |
| 핵심 답변 | Request ID = 응답 헤더 X-Shellapi-Request-Id, 오류 message 끝의 (request id: ...) 와 같은 값 |
| 추가된 내용 | 두 가지 확인 방법, ID 대조표, 콘솔 로그에 ID 가 표시되지 않는 이유, 비동기 영상 설명, ID 를 찾을 수 없을 때 대처법, 티켓 템플릿 |
| 보안 안내 | Request ID 는 키가 아니므로 티켓, 채팅, 스크린샷에 붙여도 됩니다. 외부에 공유하면 안 되는 것은 sk- 로 시작하는 전체 API 키예요 |
| 영향 범위 | APIYI 에서 텍스트, 이미지, Embedding, Claude Messages, Responses, 비동기 영상 API 를 호출하는 모든 개발자 |
문서 원문에 따르면 이 응답 헤더의 이름은 대소문자를 구분하지 않아요. 성공한 요청, 비즈니스 오류, 스트리밍 요청 모두 이 헤더를 반환하고, 스트리밍 요청의 응답 헤더는 첫 번째 데이터 블록보다 먼저 도착해요. 비동기 영상 API 의 제출과 조회 요청도 모두 이 값을 반환합니다.
APIYI Request ID, 이제 어느 문자열을 복사해야 할까: 두 가지 경로
먼저 형식부터 확인해요. APIYI의 Request ID는 14자리 UTC 시간으로 시작해요. 예를 들어 2026111602224568279882196e93ae3kTS58ypN에서 앞 14자리 20261116022245는 2026-11-16 02:22:45 UTC, 즉 베이징 시간 10:22:45예요. 이 접두사를 자신의 호출 시간과 맞춰 보면 잘못 가져왔는지 대체로 판단할 수 있어요.

경로 1: 오류 JSON에서 바로 복사하기
이 방법은 대부분의 클라이언트 사용자에게 적합해요. 오류가 나면 오류 JSON의 message 필드 끝에 (request id: ...)가 붙는데, 괄호 안의 문자열을 통째로 복사하면 됩니다.
- 클라이언트나 로그 출력에서 전체 오류 JSON을 찾으세요.
message필드의 끝을 찾으세요.request id:뒤의 문자열 전체를 잘리지 않게 복사하세요.
콘솔 로그: 호출은 확인할 수 있지만 Request ID는 표시되지 않아요
많은 분이 가장 먼저 콘솔의 “로그” 페이지에서 ID를 찾으려고 해요. 최신 문서에는 이 내용을 다룬 섹션이 따로 있어요: 로그 페이지에는 X-Shellapi-Request-Id가 표시되지 않고, 이 값으로 검색하는 기능도 없어요.
로그에서 볼 수 있는 건 시간, 모델, 토큰 이름, 스트리밍/비스트리밍, 소요 시간, 상태, 입력/출력 토큰, 비용, 그룹, 배율, IP예요. 이 정보만으로 이번 호출이 APIYI에 도착했는지, 어떤 모델을 사용했는지, 얼마가 차감됐는지는 충분히 확인할 수 있어요. 하지만 장애 신고에서 문제를 특정하는 용도로는 쓸 수 없어요.
따라서 장애를 신고할 때 ID를 얻을 수 있는 곳은 두 군데뿐이에요: 오류 원문(경로 1)과 응답 헤더(경로 2)예요. 로그는 시간, 모델, 토큰, 비용 같은 보충 자료로 쓰면 됩니다.
경로 2: 코드에서 응답 헤더 읽기
자동으로 오류를 수집할 때는 코드에서 이 헤더를 직접 기록하는 걸 권장해요. 어떤 방식을 쓰든 Base URL은 https://api.apiyi.com/v1이어야 합니다.
- cURL:
curl -D headers.txt로 응답 헤더를 파일에 기록한 뒤, 파일에서x-shellapi-request-id를 찾으세요. 임시로 확인할 때는curl -i로 바로 출력해도 됩니다. - Python requests: 응답 객체를 받은 뒤
r.headers.get("x-shellapi-request-id")를 읽으세요. 성공할 때와 오류가 날 때 모두 읽을 수 있어요. - OpenAI SDK(Python): 일반 반환값의
_request_id는x-request-id를 읽기 때문에 APIYI에서는 보통 비어 있어요. 올바른 방법은client.chat.completions.with_raw_response.create(...)를 사용해raw.headers.get("x-shellapi-request-id")를 읽고,raw.parse()로 결과를 가져오는 거예요. 오류가 나면except openai.APIStatusError as e안에서e.response.headers를 읽으세요. - Node.js: fetch를 쓸 때
res.headers.get("x-shellapi-request-id")를 읽으세요. - Postman: 요청을 보낸 뒤 응답 영역의 Headers 탭을 열어
X-Shellapi-Request-Id를 찾으세요. - 브라우저 프런트엔드: 교차 출처 호출은 CORS 제한을 받아 JS에서 이 헤더를 읽을 수 없어요. 백엔드 프록시에서 기록하거나, 개발자 도구의 Network → 해당 요청 → Response Headers에서 확인하세요.
🚀 빠른 시작: 내 코드가 이 헤더를 읽을 수 있는지 확인하려면 APIYI apiyi.com의 토큰으로 최소 요청을 한 번 보내고, 14자리 시간으로 시작하는 ID가 출력되는지 확인해 보세요. 이 과정에서 소량의 토큰이 소모되니 출력이 아주 짧은 프롬프트를 선택하는 걸 권장해요.
APIYI Request ID가 아닌 ID들
하나의 응답 안에 여러 종류의 “ID”가 동시에 나타날 수 있어서, 많은 문의 티켓이 바로 이 단계에서 막히곤 해요. 새 문서에 비교표가 마련되어 있는데, 핵심만 아래에 정리해 볼게요.

| 필드 | 출처 | 장애 신고 시 로그 조회 가능 여부 | 식별 특징 |
|---|---|---|---|
| X-Shellapi-Request-Id | APIYI | ✅ 바로 이것 | 14자리 UTC 시간으로 시작 |
| X-Oneapi-Request-Id | 중간 계층 | ❌ | 헤더 이름이 다름 |
| X-Request-Id | 업스트림 원 제공사 | ❌ APIYI 로그에서는 검색되지 않음 | 흔히 req_로 시작하거나 UUID |
| 기타 채널 커스텀 헤더 | 채널 | ❌ | 헤더 이름이 제각각 |
응답 본문 id |
Completion ID / Response ID | ❌ | chatcmpl-, resp_로 시작 |
이미지 generation_id |
이미지 생성 결과 | ❌ | 응답 본문 안에 있음 |
task_id |
비동기 작업 | ❌ Request ID는 아니지만 함께 제공해야 함 | 작업 조회, 과금 조회 |
판단 규칙은 아주 간단해요. 시작 부분이 14자리 시간이 아니면 모두 APIYI의 Request ID가 아니에요. 만약 받은 ID가 req_로 시작한다면, 요청이 OpenAI 공식 쪽으로 직접 들어갔을 가능성이 있어요. 이럴 때는 먼저 Base URL이 https://api.apiyi.com/v1로 되어 있는지 확인해 보세요.
비동기 비디오의 task_id와 Request ID를 어떻게 나눠 저장할까
비동기 비디오는 “제출”과 “조회” 두 단계로 나뉘고, 각 단계마다 새로운 X-Shellapi-Request-Id가 반환돼요. 거기에 작업 ID까지 더하면 쉽게 뒤섞이죠. 새 문서의 권장 사항은 이래요. 제출 요청의 Request ID와 폴링에 쓰는 작업 ID를 따로 저장하세요.
| 모델 | 작업 ID 위치 | 조회 인터페이스 | 헷갈리기 쉬운 필드 |
|---|---|---|---|
| Seedance | 응답 본문 최상위 id (필드 이름이 task_id가 아님) |
GET /seedance/api/v3/contents/generations/tasks/{id} |
— |
| Wan / HappyHorse | output.task_id |
GET /v1/tasks/{task_id} |
응답 본문의 request_id는 업스트림 것이고, APIYI 로그에 있는 그 값이 아님 |
실제로 저장할 때는 작업마다 필드 3개를 두는 걸 권장해요. 제출 시의 X-Shellapi-Request-Id, 작업 ID, 제출 시간이에요. 작업 조회 시 반환되는 Request ID는 필요할 때 기록하면 돼요. 제출이 실패했을 때 문의용으로는 Request ID를 쓰고, 작업이 멈췄거나 과금이 의심될 때는 작업 조회와 과금 조회 모두에 작업 ID가 필요해요.
로그에서 Request ID가 안 보일 때 무엇을 보충할까
ID를 받았다 해도 로그에서 꼭 찾을 수 있는 건 아니에요. 새 문서는 “콘솔 로그에 Request ID가 없다”는 상황을 별도 섹션으로 뺐고, 그 밖의 못 찾는 경우들은 아래처럼 대응하면 돼요.
| 상황 | 원인 | 보충할 것 |
|---|---|---|
| 응답을 받기 전에 요청이 실패 | DNS, TCP/TLS, 프록시 거부, 클라이언트 타임아웃 — 응답 헤더 자체가 없음 | 오류 원문, 호출 시간, 네트워크 환경 설명 |
| 클라이언트에 “요청 실패”만 표시됨 | 클라이언트가 원래 오류를 노출하지 않음 | 경로 1 또는 경로 2로 ID 확보, 로그로는 호출 도달 여부만 확인 가능 |
ID가 req_로 시작 |
OpenAI 공식으로 잘못 요청했을 수 있음 | Base URL 확인 후 재시도 |
| 로그에서도 검색 안 됨 | 보존 기간 초과, 또는 잘못된 ID | ID 형식 확인, 로그는 당월과 그 이전 두 개 자연월만 보존 |
한 가지 더요. 콘솔 페이지에는 ID가 표시되지 않지만, 로그 조회 API로는 request_id 기준 조회가 가능해요. 아래 표는 2026-11-16에 실제 호출로 확인한 내용이고, 모델은 deepseek-flash와 gpt-image-2, 요청은 https://api.apiyi.com/v1로 보냈어요.
| 호출 | HTTP 상태 | 응답 헤더 | 로그에서 request_id로 조회한 결과 |
|---|---|---|---|
| deepseek-flash 비스트리밍 | 200 | x-shellapi-request-id 있음, x-request-id 없음 | 정확히 소비 기록 1건 조회됨 |
| deepseek-flash 스트리밍 | 200 | 있음, 첫 data: 블록 이전에 읽을 수 있음 |
— |
| gpt-image-2, size=999×999 | 400 | message 끝의 request id와 같은 값 | 오류/재시도 기록 3행, 소비 행 없음 |
| 존재하지 않는 모델명 | 503 | message 끝의 request id와 같은 값 | 한 행도 조회 안 됨 |
결론은 이래요. 콘솔 로그 페이지는 Request ID를 표시하지 않지만, 로그 조회 API로는 request_id 기준으로 “소비 행”과 “오류 행”을 찾을 수 있어요. 다만 매번 있다고 보장할 수는 없어요. 요청이 채널까지 도달한 뒤 채널 측에서 실패한 경우(예: 파라미터 오류)는 오류 행이 남아요. 게이트웨이 계층에서 그 자리에서 거부된 경우(예: 사용 가능한 채널 없음)는 한 행도 없을 수 있어요. 못 찾을 때는 응답 헤더나 오류 원문에 있는 ID에 호출 시간을 붙여 자료를 보충하면 돼요.
고객 지원에서 재현이 필요하면 APIYI apiyi.com에서 같은 토큰, 같은 파라미터 조합으로 한 번 더 호출해 보거나, 다른 모델로 바꿔 같은 오류인지 비교해 보세요. 재현에도 토큰이 소모되니, 재현할 때마다 Request ID를 함께 기록해 두세요.
🎯 트러블슈팅 팁: 오류를 재현할 때는 Base URL을
https://api.apiyi.com/v1로 고정하고, 매번 X-Shellapi-Request-Id와 호출 시간을 기록하세요. 이후 ID와 호출 시간을 함께 고객 지원에 전달하면, 백엔드에서 ID로 조회해 오류가 게이트웨이 계층에서 났는지 채널 계층에서 났는지 더 빠르게 확인할 수 있어요.
APIYI Request ID 오류 티켓 템플릿
아래 항목들을 그대로 복사해서 티켓에 채워 넣으면 돼요:
- Request ID: 14자리 시간 값으로 시작하는 문자열
- 모델: 예: gpt-image-2
- 인터페이스: 예: POST /v1/chat/completions
- 시간: 시간대 포함, 예: 2026-11-16 11:24:04 UTC+8
- HTTP 상태: 예: 400 / 503
- 오류 메시지:
(request id: ...)를 포함한 전체 오류 내용을 붙여넣기 - 이미 시도한 것: 예: 모델 교체 완료, Base URL 확인 완료, 2회 재시도 완료
- task_id(비동기 비디오 전용): 제출 시 반환된 작업 ID
두 가지만 주의하세요. 전체 API 키는 절대 보내지 말고, 요청 본문이나 이미지에 개인정보가 담겨 있다면 먼저 비식별화한 뒤 제출하세요.
Request ID 문서 업그레이드가 개발자에게 미치는 영향
개발자에게 미치는 영향
- 장애 보고가 한 단계 줄어요: 처음부터 올바른 ID를 넘기면 상담원이 다시 되물을 필요가 없어요.
- SDK 사용자는 더 이상 빈 값을 받지 않아요:
_request_id의 함정과with_raw_response에서 값을 꺼내는 방법을 명확히 정리했어요. - 비디오 작업을 추적할 수 있어요: Request ID와 작업 ID를 따로 저장하면 작업 조회와 과금 조회 모두 근거가 확실해져요.
예전 문서를 볼 때 주의할 점
일부 인터페이스 기능 페이지, 뉴스 페이지, 오류 기록 보관 성격의 페이지에서는 여전히 x-request-id를 “이걸 기록해 두면 문제 파악이 편하다”는 정도로만 설명하고 있어요. 이런 표현을 만나면 새 버전 Request ID 페이지를 기준으로 삼으세요. 코드 템플릿에 있는 x-request-id도 x-shellapi-request-id로 바꿔 주세요.
자주 묻는 질문 FAQ
Q1: APIYI Request ID는 정확히 어느 것인가요?
응답 헤더의 X-Shellapi-Request-Id이고, 14자리 UTC 시간으로 시작해요. 오류가 발생했을 때 오류 message 끝의 `(request id: …)` 안에 있는 값과 동일해요.
Q2: Request ID를 다른 사람에게 보내도 안전한가요?
안전해요. 문서 원문에 따르면 Request ID는 키가 아니므로 티켓, 채팅, 스크린샷에 붙여도 돼요. 외부로 보내면 안 되는 것은 `sk-`로 시작하는 전체 API 키예요.
Q3: OpenAI SDK에서 읽은 ID가 왜 비어 있나요?
SDK 기본 `_request_id`는 x-request-id를 읽어요. `with_raw_response`를 사용하거나 `APIStatusError`의 응답 헤더에서 x-shellapi-request-id를 가져오면 돼요.
Q4: 올바른 Request ID를 받을 수 있는지 빠르게 확인하려면 어떻게 해야 하나요?
1. APIYI apiyi.com에서 가입하고 API 키를 발급받으세요. 신규 사용자에게는 무료 테스트 크레딧이 있어요.
2. Base URL을 `https://api.apiyi.com/v1`로 설정하고 최소 요청을 한 번 보내세요.
3. x-shellapi-request-id를 출력해서 매 호출마다 이 ID 문자열을 받을 수 있는지 확인하세요. 로그 페이지에서는 이번 호출이 도달했는지와 과금 여부만 확인할 수 있고, ID는 표시되지 않아요.
Q5: 3개월 전 오류도 조회할 수 있나요?
일반적으로 조회할 수 없어요. 로그는 해당 월과 이전 두 개 자연월까지 보관되므로, 더 이전 기록은 직접 저장한 Request ID와 오류 원문으로 설명해야 해요.
APIYI Request ID 핵심 포인트 Key Takeaways
- 유일하게 올바른 ID: X-Shellapi-Request-Id, 14자리 UTC 시간으로 시작해요
- 두 가지 확인 방법: 에러 message에서 복사하거나 코드에서 응답 헤더를 읽으면 돼요 (로그는 호출 여부만 확인할 수 있고 ID는 보여주지 않아요)
- 흔히 잘못 가져오는 ID: X-Request-Id,
req_,chatcmpl-,resp_, UUID는 모두 장애 신고에 사용할 수 없어요 - 비디오는 두 개를 저장: 제출한 Request ID와 작업 ID를 따로 보관하세요
- 로그가 전부는 아니에요: 콘솔 페이지에는 ID가 표시되지 않아요; 게이트웨이가 그 자리에서 거부한 요청은 기록조차 없을 수 있으니 에러 원문과 시간을 함께 보충해야 해요
- 직접 검증하기: APIYI apiyi.com에서 최소 요청을 한 번 보내면 이 헤더를 읽을 수 있는지 바로 확인할 수 있어요
요약
APIYI Request ID 조회 문서의 이번 업그레이드, 핵심은 딱 세 가지예요:
- 답을 앞에 제시: Request ID는 바로 X-Shellapi-Request-Id이고, 에러 message 끝에도 같은 값이 있어요.
- 잘못된 ID 배제: 대조표에 중간 계층, 업스트림, 응답 본문, 작업 ID의 차이를 명확히 정리했어요.
- 못 찾을 때의 대비책: 네 가지 상황별로 무엇을 보충해야 하는지, 바로 쓸 수 있는 티켓 템플릿을 함께 제공해요.
지금 바로 코드의 에러 로그 필드를 x-shellapi-request-id로 바꾸는 걸 권장해요. 앞으로 문제가 생기면 ID와 호출 시간을 함께 고객 지원에 전달하고, 백엔드에서 ID로 조회한 뒤 완전한 자료를 갖춰 티켓을 제출하세요.
📚 참고 자료
- APIYI Request ID 진단 문서(신버전): 이 글의 사실 근거예요
- 링크:
docs.apiyi.com/faq/request-id-troubleshooting -
설명: 두 가지 추출 방법, 콘솔 로그 설명, ID 대조표, 비동기 영상 설명, 티켓 템플릿을 담고 있어요
-
로그 보관 기간: 로그 보존 기간 안내
- 링크:
docs.apiyi.com/faq/log-retention-policy - 설명: 오류 기록을 아직 조회할 수 있는지 확인할 수 있어요
작성자: APIYI 기술팀
기술 교류: APIYI apiyi.com 웹사이트 첫 페이지에서 문의해 주세요. 티켓을 제출할 때 X-Shellapi-Request-Id를 첨부하면 처리가 더 빨라져요
