Claude 연동이 끝났다는 표시만으로 사용량 화면까지 믿을 수 있는 것은 아니었습니다. 나는 실제로 숫자가 보이는지, 무엇을 뜻하는지, 끊겼을 때 어떻게 달라지는지까지 확인한 뒤에야 이 기능을 사용할 수 있다고 판단했습니다.
한 줄 요약: 사용량 표시는 숫자 하나가 아니라 기준 시점·집계 범위·오류 상태를 함께 읽을 수 있어야 합니다.
1. 숫자가 즉시 보이는지보다, 기준 시점이 보이는지를 먼저 봤습니다
연동 직후 값이 비어 있거나 이전 값이 남아 있을 수 있습니다. 그래서 표시된 수치만 보지 않고 마지막 갱신 시점, 새로고침 뒤 변화, 집계가 늦을 수 있다는 안내가 함께 있는지를 점검했습니다. 기준 시점이 빠지면 같은 숫자도 현재 사용량인지 과거 기록인지 알 수 없습니다.
2. 사용량의 범위와 단위를 분리해서 읽었습니다
사용량이라는 말에는 요청 수, 토큰, 비용, 한도 소진 비율처럼 서로 다른 값이 섞이기 쉽습니다. 나는 화면에 어떤 단위가 표시되는지와 일간·주간·월간 중 어느 범위인지 따로 점검했습니다. 특히 남은 비율만 보여 주는 화면은 절대 사용량으로 해석하지 않도록 구분했습니다.
3. 0이라는 값과 불러오지 못한 상태를 구분했습니다
가장 조심한 부분은 0입니다. 실제 사용량이 0인지, 권한이나 연결 문제로 데이터를 읽지 못한 것인지는 전혀 다른 상황입니다. 오류 안내, 재시도 버튼, 마지막 정상 갱신 정보가 없는 화면이라면 0을 정상값으로 단정하지 않는 편이 안전합니다.
4. 연결이 끊긴 뒤의 행동까지 점검했습니다
정상 연결 상태의 화면만 확인해서는 부족했습니다. 갱신이 실패했을 때 이전 값을 유지하는지, 오류를 보여 주는지, 다시 연결해야 하는지를 기준으로 봤습니다. 이 확인이 있어야 사용량 화면을 운영 판단에 쓸 수 있습니다.
내 결론
이번 연동에서 내가 통과 기준으로 삼은 것은 숫자가 나타나는지 자체가 아니었습니다. 숫자의 기준 시점과 범위가 설명되고, 실패를 0으로 보이게 하지 않으며, 다시 확인할 방법이 있는지까지가 기준이었습니다. 이 네 가지가 확인되면 사용량 표시는 단순 장식이 아니라 다음 작업을 정하는 근거가 됩니다.
확인 범위: 이 글은 사용량 표시 화면을 읽고 검증하는 기준을 기록한 개발 일지입니다. 특정 요금제의 한도나 미완료 기능의 성공 여부를 뜻하지는 않습니다.
공식 문서로 보는 사용량 한도의 구조
연동 화면에서 읽어야 할 값이 무엇인지는 Claude 공식 도움말과 API 문서(2026년 10월 18일 기준)에도 단서가 있습니다. 아래는 두 문서와 MDN 문서에 적힌 내용만 옮긴 것입니다.
구독 사용량: 5시간 세션과 주간 한도
Claude 도움말은 유료 플랜에 5시간마다 초기화되는 세션 한도와 일주일에 한 번 초기화되는 주간 한도가 있다고 설명합니다. 사용량은 대화의 길이와 복잡도, 사용하는 기능, 선택한 모델, 설정한 노력 수준에 따라 달라지고, 자동 컨텍스트 관리가 일어나는 긴 대화는 한도를 더 쓴다고 합니다. claude.ai, Claude Code, Claude Desktop의 사용량은 하나의 한도를 공유합니다. 허용량은 플랜마다 다르다고도 적혀 있습니다.
이 설명이 이 글의 두 번째 점검 항목, 곧 “범위와 단위를 분리해서 읽기”와 직접 이어집니다. 5시간 창과 주간 창은 서로 다른 범위이고, 여러 앱의 사용이 한 한도로 합쳐지므로, 화면의 숫자가 어느 범위의 값인지 표시되지 않으면 해석이 달라집니다.
API 사용량: 남은 양과 초기화 시각이 헤더로 옵니다
Claude API 문서는 응답 헤더에 한도, 남은 양, 한도가 다시 채워지는 시각(RFC 3339 형식)이 담긴다고 설명하고, 토큰 잔량은 천 단위로 반올림된다고 적습니다. 속도 제한은 토큰 버킷 방식이라 고정된 간격으로 한꺼번에 초기화되지 않고 용량이 계속 채워집니다. 월 지출 한도에 걸리면 429 응답이 오는데 retry-after 헤더는 없고, 접근이 재개될 때까지 재시도는 실패한다고 합니다. 이 상태는 “사용량 0”이 아니라 “한도 도달”이므로 세 번째 점검 항목(0과 불러오지 못한 상태 구분)과 같은 맥락입니다.
끊김과 재시도
MDN 문서에 따르면 429는 짧은 시간에 요청이 너무 많았다는 뜻의 상태 코드이고, 응답에 Retry-After가 포함될 수 있습니다. 포함 여부는 서버마다 다릅니다. 그래서 갱신이 실패했을 때 화면이 이전 값을 유지하는지, 오류를 보여 주는지를 정하는 네 번째 점검 항목은 서버 응답이 항상 친절하지 않다는 전제에서 필요합니다.
| 점검 항목 | 공식 문서에 적힌 근거 |
|---|---|
| 기준 시점 | 초기화 시각이 RFC 3339 형식으로 제공되고 토큰 잔량은 반올림됨 |
| 범위와 단위 | 5시간 세션 한도와 주간 한도가 따로 있고 여러 앱이 한도를 공유함 |
| 0과 미확인 구분 | 지출 한도 도달 시 429이며 retry-after가 없음 |
| 끊긴 뒤 동작 | 429에는 Retry-After가 포함될 수도, 아닐 수도 있음 |
플랜별 허용량과 정책은 바뀔 수 있으므로 실제 한도는 Claude의 최신 도움말과 계정 화면이 우선입니다.
확인 자료
기준일: 2026-10-18