TokenLab Request Console: 하나의 대시보드에서 AI API 호출 디버깅하기

AI API 호출 실패는 좀처럼 명확하게 드러나지 않습니다. 상태 코드와 오류 문자열 정도만 확인될 뿐이며, 지원 채널에 문의하면 '요청 ID(request ID)가 무엇인가요?'라는 질문을 받게 됩니다. 만약 요청 ID를 바로 찾을 수 없다면, 조사조차 시작하기 전에 막히게 됩니다. 저희는 이러한 문제를 해결하기 위해 요청 수준의 세부 정보를 하나의 대시보드 뷰에서 확인할 수 있는 TokenLab Request Console을 구축했습니다. 이 콘솔은 모델, 키, 캐시 상태, 결제 상태, 타이밍 및 마스킹 처리된 페이로드 미리보기를 보여줍니다. 저희 파이프라인에서는 요청 ID를 첫 번째 조회 키로 사용합니다.

핵심 요약

• TokenLab Request Console은 결제 보고서가 아닌, TokenLab API 대시보드 내의 요청 수준 디버깅 인터페이스입니다.
• 모든 요청에는 직접 검색할 수 있는 ID가 있습니다. URL에 requestId를 포함하여 특정 요청으로 바로 연결(deep-link)할 수 있습니다.
• 콘솔은 최근 요청에 대한 라우팅, 결제 상태, 캐시 상태, 모델/키 컨텍스트 및 마스킹 처리된 페이로드 미리보기를 보여줍니다.
• 액세스 권한은 조직 단위로 범위가 지정되며 대시보드 멤버십 권한에 따라 관리됩니다. 팀원은 자신의 역할이 허용하는 범위 내의 데이터만 볼 수 있습니다.
• 단일 사고 디버깅에는 콘솔을 사용하고, 기간별 배치 비용 검토에는 사용량 내보내기(usage exports)를 사용하세요.

TokenLab Request Console이란?

이 기능은 TokenLab 대시보드의 API 섹션 내 /dashboard/api?tab=requestConsole에서 확인할 수 있습니다. API 대시보드 자체는 /dashboard/api에 위치합니다. 이 콘솔은 '요청이 실패했을 때 가장 빠른 해결책은 오류 메시지만 보고 추측하는 것이 아니라, 전체 컨텍스트를 눈앞에서 확인하는 것'이라는 전제하에 구축되었습니다.

대시보드 설명에 따르면 이 콘솔은 라우팅, 결제, 요청/응답 본문, 모델 공급업체 컨텍스트를 포함하여 최근 요청을 검사하는 도구입니다. 콘솔은 다음과 같은 몇 가지 작업 섹션으로 나뉩니다.

목록 뷰(List view). 최근 요청을 필터링할 수 있는 테이블입니다. 특정 요청 ID를 아직 모를 때 여기서 시작합니다. 실패했거나 비정상적인 호출을 찾기 위해 스캔하는 곳입니다.

검사기 패널(Inspector panel). 요청을 선택하면 검사기가 열리며 어떤 모델이 처리했는지, 어떤 API 키가 사용되었는지, 캐시를 적중했는지, 최종 상태가 무엇인지 등의 전체 세부 정보가 표시됩니다.

오류 컨텍스트(Error context). 요청이 실패한 경우, 콘솔은 해당 특정 호출과 관련된 오류 정보를 보여줍니다. 별도의 오류 로그를 대조할 필요가 없습니다.

라우팅 및 결제 상태(Route and billing state). 요청이 어떻게 라우팅되었는지, 결제됨, 대기 중, 환불됨, 실패 중 어떤 상태인지 보여줍니다. 고객이 '그 오류에 대해 요금이 청구되었나요?'라고 물을 때 가장 중요한 정보입니다.

페이로드 미리보기(Payload preview). 요청 및 응답 본문은 가능한 경우 마스킹 처리된 미리보기로 표시되어, 본문의 원본 비밀 정보를 노출하지 않으면서도 형태와 구조를 파악할 수 있게 합니다.

모델 공급업체 및 모델 키 컨텍스트(Model vendor and model key context). 어떤 공급업체와 어떤 특정 모델이 호출을 처리했는지 보여줍니다. 하나의 통합 환경 뒤에서 여러 모델을 실행하고 올바른 모델이 호출되었는지 확인해야 할 때 유용합니다.

이 모든 과정에서 API 위에 별도의 로깅 파이프라인을 직접 구축할 필요가 없습니다. 이미 조직별로 노출되며 대시보드 멤버십 권한에 따라 필터링되므로, 적절한 권한을 가진 팀원은 동일한 요청 데이터를 확인할 수 있습니다.

가장 먼저 확인해야 할 사항

API 호출이 실패하면 확인해야 할 자연스러운 순서가 있습니다. 요청이 올바른 엔드포인트에 도달했는지 확인하기도 전에 '모델이 다운되었나?'라고 생각하며 뛰어드는 것은 시간 낭비입니다.

5가지 필드 트리아지(Triage)

확인 항목	확인 내용
요청 ID	비슷한 호출이 아닌 정확히 해당 호출을 보고 있는지 확인
상태	결제됨, 대기 중, 환불됨, 실패 중 하나로, 비용 문제인지 기술적 문제인지 파악
모델	실제로 요청을 처리한 모델 (여러 모델을 라우팅할 때 유용)
캐시 상태	프롬프트 캐시 적중 또는 미적중이 비용이나 지연 시간에 영향을 주었는지 확인
키 소스	어떤 API 키가 사용되었는지 확인 (여러 키나 환경이 통합을 공유할 때 유용)

요청 ID부터 시작하세요. 클라이언트 측 로그, 지원 티켓 또는 오류 보고서에서 ID를 확보했다면 다음 딥링크 패턴을 사용하세요:

/dashboard/api?tab=requestConsole&requestId=%3Crequest_id>

이렇게 하면 목록 뷰를 건너뛰고 해당 요청에 대한 검사기가 바로 열립니다. 누군가 ID를 건네주며 '무슨 일이 있었나요?'라고 물을 때 가장 빠른 경로입니다.

아직 요청 ID가 없다면 콘솔의 필터를 사용하여 모델, 시간 범위, 프롬프트 캐시 상태, 키 소스 및 상태별로 좁힐 수 있습니다. 예를 들어 요청이 실패했을 때, 지난 1시간 이내의 '실패' 상태로 필터링한 다음 사용자가 문의한 특정 호출을 목록에서 찾으세요.

상태 필드를 올바르게 읽는 법

결제됨, 대기 중, 환불됨, 실패라는 네 가지 상태는 각각 다른 질문에 답을 줍니다:

• 결제됨(Billed)은 호출이 완료되어 크레딧이 소모되었음을 의미합니다. 사용자가 오류를 보고했는데 요청이 결제됨으로 표시된다면, 이는 별도로 표시해둘 가치가 있습니다. 성공적인 응답 이후 클라이언트 측에서 실패가 발생했을 가능성을 시사합니다.
• 대기 중(Pending)은 요청이 아직 진행 중이거나 정산을 기다리고 있음을 의미합니다. 이를 성급하게 실패로 간주하지 마세요.
• 환불됨(Refunded)은 TokenLab이 요금을 취소했음을 의미하며, 일반적으로 공급업체나 라우팅 측의 실패와 관련이 있습니다.
• 실패(Failed)는 호출이 성공적으로 완료되지 않았으며 결제되지 않았음을 의미합니다.

에스컬레이션하기 전에 이 중 어떤 상태가 적용되는지 알면 지원팀과의 불필요한 소통을 줄일 수 있습니다.

모델 및 캐시 상태 확인

공유 통합을 통해 Claude Sonnet 5, DeepSeek V4 Pro, Gemini 3.5 Flash와 같은 모델에 요청을 보내는 경우, 콘솔에 예상한 모델이 표시되는지 확인하세요. 잘못 구성된 클라이언트, 오래된 환경 변수 또는 라우팅 재정의로 인해 클라이언트 측에서 명확한 오류 없이 트래픽이 잘못된 모델로 전송될 수 있습니다.

캐시 상태는 비용과 지연 시간이라는 두 가지 이유로 중요합니다. 적중을 예상했는데 캐시 미적중이 발생했다면, 일반적으로 프롬프트 접두사가 미세하게라도 변경되었음을 의미합니다. 타임스탬프, 재정렬된 필드 또는 추가 공백 문자가 있는지 확인하세요. 콘솔의 캐시 상태 필터를 사용하면 적중 및 미적중 요청을 나란히 비교할 수 있습니다.

TokenLab Request Console과 사용량 내보내기(Usage Exports)의 관계

Request Console과 사용량 내보내기는 서로 다른 문제를 해결하므로 경계를 명확히 하는 것이 좋습니다. 콘솔은 단일 요청 조사(하나의 호출, 하나의 오류, 하나의 결제 질문)를 위해 만들어졌으며 검사기 패널에서 즉시 답을 얻을 수 있습니다. 특정 요청이 실패하여 그 이유를 지금 당장 알아야 할 때 여는 곳입니다.

사용량 내보내기는 집계 검토(기간별 지출, 모델 또는 키별 분석 등)를 위해 만들어졌으며, 재무 담당자에게 보고하거나 월별 정산에 사용하는 유형의 보고서입니다. '지난주 DeepSeek V4 Pro에 얼마를 썼는가?'라는 질문에 답하고 싶다면 콘솔이 아닌 내보내기를 사용해야 합니다. 해당 워크플로우는 TokenLab 대시보드 사용량 내보내기 가이드를 참조하세요.

요약하자면, 사고 발생 시에는 콘솔을, 총액 확인 시에는 내보내기를 사용하세요. 일부 팀은 두 가지를 순차적으로 사용합니다. 내보내기를 통해 집계 지출에서 이상 징후를 발견하고, 콘솔을 통해 그 원인이 된 특정 요청을 파고드는 방식입니다.

실용적인 디버깅 루틴

임시방편적인 디버깅은 압박 속에서 추측으로 변질됩니다. 반복 가능한 루틴을 갖추면 사고 처리 시간을 단축할 수 있습니다.

체크리스트: 요청 실패 시

1. 요청 ID 확보. 클라이언트 로그, 오류 응답 또는 사용자 보고서에서 확인합니다. 현재 요청 ID를 기록하고 있지 않다면 지금부터 시작하세요. 가장 빠른 조회 키입니다.
2. 딥링크로 콘솔 열기. requestId 쿼리 매개변수를 사용하여 검사기로 바로 이동합니다.
3. 상태 필드 먼저 확인. 결제됨, 대기 중, 환불됨, 실패 중 무엇인지 확인하여 조사의 방향을 잡습니다.
4. 실제로 처리한 모델 확인. 예상한 모델과 비교합니다.
5. 캐시 상태 확인. 예상치 못한 지연 시간이나 비용은 캐시 미적중 때문일 수 있습니다.
6. 키 소스 확인. 특히 스테이징과 프로덕션 환경을 구분할 때 올바른 API 키와 환경이 사용되었는지 확인합니다.
7. 오류 컨텍스트 및 라우팅 정보 읽기. 보통 여기서 근본 원인이 드러납니다.
8. 마스킹 처리된 페이로드 미리보기 검토. 요청 형태가 클라이언트가 보낸 것과 일치하는지 확인합니다. 잘못된 매개변수는 다른 곳보다 여기서 먼저 발견되는 경우가 많습니다.
9. 필요 시 API 레퍼런스 참조. https://docs.tokenlab.sh/api-reference/chat/create-completion에 있는 TokenLab 채팅 완성 API 레퍼런스는 예상되는 요청 및 응답 형태를 문서화하고 있습니다. 이를 통해 클라이언트 측에서 페이로드가 잘못되었는지 확인하세요.
10. 일회성이 아닌 패턴이라면 사용량 내보내기로 전환. 단일 실패는 콘솔 문제이지만, 한 시간 동안 10번의 실패가 발생했다면 집계하여 검토할 가치가 있는 패턴입니다.

ID, 상태, 모델, 캐시, 키, 오류, 페이로드 순서로 확인하면 실패의 원인을 설명하는 필드를 놓치지 않을 수 있습니다.

FAQ

요청 ID 없이 실패한 요청을 어떻게 찾나요?

TokenLab Request Console의 목록 뷰 필터를 사용하세요. 모델, 시간 범위, 프롬프트 캐시 상태, 키 소스 및 상태별로 좁힐 수 있습니다. 예를 들어 지난 1시간 이내의 '실패' 상태로 필터링한 후 사용자가 문의한 호출을 찾으세요. 찾은 후에는 검사기를 열고 나중을 위해 요청 ID를 복사해두세요.

클라이언트는 오류를 보고하는데 왜 요청은 '결제됨'으로 표시되나요?

결제됨은 호출이 완료되어 크레딧이 소모되었음을 의미합니다. 사용자가 오류를 보고했는데 요청이 결제됨으로 표시된다면, 성공적인 응답 이후 클라이언트 측에서 실패가 발생했을 가능성이 높습니다. 이는 실패하거나 환불된 요청과는 다른 해결 경로가 필요하므로 별도로 표시해두세요.

검사기에서 캐시 미적중은 무엇을 의미하나요?

캐시 미적중은 요청이 프롬프트 캐시를 적중하지 못했음을 의미하며, 이는 비용과 지연 시간에 영향을 줍니다. 적중을 예상했는데 미적중이 발생했다면 일반적으로 프롬프트 접두사가 미세하게라도 변경되었음을 의미합니다. 타임스탬프, 재정렬된 필드 또는 추가 공백 문자가 있는지 확인하세요.

팀원과 요청 링크를 공유할 수 있나요?

네, 팀원의 대시보드 멤버십 권한이 허용하는 경우 가능합니다. 요청 데이터는 조직 단위로 범위가 지정됩니다. /dashboard/api?tab=requestConsole&requestId=<request_id> 형식의 딥링크를 사용하여 검사기를 직접 여세요. 팀원은 자신의 역할이 허용하는 데이터만 볼 수 있습니다.

언제 콘솔에서 사용량 내보내기로 전환해야 하나요?

문제가 일회성이 아닌 패턴일 때 전환하세요. 단일 실패는 콘솔 문제이지만, 한 시간 동안 10번의 실패가 발생했다면 집계하여 검토할 가치가 있는 패턴입니다. 기간별 지출, 모델 또는 키별 분석, 월별 정산에는 내보내기를 사용하세요.

출처 및 최신 정보

• TokenLab Request Console — /dashboard/api?tab=requestConsole — 2026-07-09 관찰됨
• TokenLab 채팅 완성 API 레퍼런스 — https://docs.tokenlab.sh/api-reference/chat/create-completion — 2026-07-09 관찰됨
• TokenLab 대시보드 사용량 내보내기 — /blog/tokenlab-dashboard-usage-exports — 2026-07-09 관찰됨
• TokenLab 공개 모델 디렉토리 — /models — 2026-07-09 관찰됨
• TokenLab API 키 대시보드 — /dashboard/api — 2026-07-09 관찰됨

참조된 모델 예시(Claude Sonnet 5, DeepSeek V4 Pro, Gemini 3.5 Flash)는 2026-09-19 기준 현재 모델 SSOT를 반영합니다. 이 콘솔 노트의 소스 스냅샷은 2026-07-09에 관찰되었으며, 소스의 원본 모델 SSOT 날짜는 2026-07-07입니다.

다음 단계

현재 클라이언트 측 로그를 grep하고 별도의 결제 대시보드를 대조하여 AI API 실패를 디버깅하고 있다면, Request Console이 그 과정을 단축해 줄 것입니다. 콘솔은 /dashboard/api?tab=requestConsole에 있습니다. API 키 대시보드는 tokenlab.sh/dashboard/api에 있습니다. 채팅 완성 요청/응답 형태는 https://docs.tokenlab.sh/api-reference/chat/create-completion에 문서화되어 있습니다. 총 지출 검토는 사용량 내보내기를 사용하세요. 모델 가격 및 컨텍스트 윈도우 세부 정보는 모델 디렉토리를 참조하세요. 지금 콘솔을 열고 ID를 통해 최근 실패한 요청을 찾아보세요.