Claude Code 지출 상한 — 중간에 끊어도 청구되고, DB가 멈추면 그냥 통과됩니다

AI 요금 얘기를 쓸 때마다 같은 벽에 부딪혔습니다. "한 사람이 이 이상은 못 쓰게" 막는 절대값이 어디에도 없다는 것요. 알림은 있고, 대시보드도 있는데, 넘으면 실제로 멈추는 장치는 잘 안 보였습니다. 그런데 이번에 열어본 문서에는 그게 있었습니다 — 개발자 한 명당 하루·주·월 단위로 금액을 걸고, 넘으면 그다음 요청부터 차단합니다. 다만 읽다 보니 예상과 다른 대목이 세 군데 나왔습니다.

📌 30초 요약

• 사람별 지출 상한은 게이트웨이를 세워야 걸 수 있습니다. 일·주·월 세 기간이 각각 따로 강제됩니다.
• 응답을 중간에 끊어도 청구됩니다. 이미 나온 글자를 네 글자당 출력 토큰 하나로 쳐서 바닥값을 매깁니다.
• 모르는 모델은 공짜가 아니라 비싼 쪽으로 계산됩니다. 100만 토큰당 5달러·25달러 기본 요율이 붙습니다.
• 집계 DB가 2초 안에 안 읽히면 기본값은 "그냥 통과"입니다. 막으려면 설정을 따로 바꿔야 합니다.
• 일일 상한은 한국시간 오전 9시에 리셋됩니다. 문서 기준이 UTC 자정이라서요.
• 그룹에 건 상한은 나눠 쓰는 예산이 아닙니다. 구성원 1인당 기본값입니다.

왜 게이트웨이가 있어야 하나

게이트웨이는 회사가 직접 돌리는 중계 서버입니다. 개발자들의 도구가 모델 회사로 곧장 가지 않고 이 서버를 거쳐 갑니다. 왜 이게 상한 얘기의 전제냐면, 문서가 이유를 이렇게 적어놨습니다 — 모든 요청이 하나의 공용 자격증명으로 나가기 때문에, 청구서에는 그 자격증명 하나만 찍히고 누가 얼마 썼는지가 안 남습니다.

그래서 문서는 이 기능을 "공용 청구서 위에 얹는 개인별 시야이자 차단기"라고 부릅니다. 뒤에 붙은 경고가 더 직접적입니다 — "개인별 상한이 없으면, 폭주한 에이전트 한 무리가 조직의 약정액을 통째로 태울 수 있다." 공식 문서가 적어둔 1인당 하루 비용을 봤을 때도 느꼈지만, 이 회사는 자기 도구가 돈을 많이 쓴다는 걸 감추지 않습니다.

거는 범위	무엇을 지정하나	참고
개인	사내 로그인 시스템이 부여한 고정 사용자 ID	가장 우선 적용
그룹	사내 계정 시스템의 그룹 이름	여러 그룹이면 기본은 제일 빡센 것
조직 전체	따로 없음. 전원 공통 기본값	개인·그룹 값이 없을 때 적용

설정은 파일이 아니라 API 호출로 합니다. 금액은 달러가 아니라 센트 단위 정수 문자열이라 5만이면 500달러입니다. 아래는 조직 전체에 월 500달러를 기본값으로 까는 요청입니다.

# 조직 전체 기본값 = 월 500달러 (50000센트)
curl -sS https://게이트웨이주소/v1/organizations/spend_limits \
  -H "x-api-key: <YOUR_ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "organization"},
      "amount": "50000", "period": "monthly"}'

금액 자리에 null을 넣으면 무제한, "0"을 넣으면 모든 요청이 막힙니다. 계정 하나를 즉시 정지시키는 스위치로 쓸 수 있다는 뜻이죠.

중간에 끊어도 청구됩니다

여기가 제일 놀란 대목입니다. 답이 길어질 것 같아서 중간에 취소해 본 적, 다들 있으실 겁니다. 문서는 그 경우를 따로 다룹니다 — 응답이 끝까지 안 왔으면 사용량 집계가 최종 수치를 못 받는데, 그때 이미 클라이언트로 나간 글자 수를 네 글자당 출력 토큰 하나로 환산해 바닥값을 매깁니다.

이유도 한 문장으로 붙어 있습니다 — "요청을 일찍 끊는 것으로 상한을 피할 수 없게." 저는 이 문장이 좋았습니다. 보통 이런 건 구현 세부라 안 적는데, "이건 회피 경로를 막으려고 넣은 것"이라고 스스로 밝혀버립니다. 덤으로 한글 네 글자 = 출력 토큰 하나라는 대략의 환산값도 얻었고요. 제가 한국어 토큰을 직접 재봤을 때와는 다른 맥락이지만, 참고할 만한 두 번째 점입니다.

요율을 정하는 순서도 명시돼 있습니다. 중요한 건 맨 아래 칸입니다.

순서	적용되는 요율	조건
1	내가 설정에 직접 적어둔 요율	특정 버전 이상에서만
2	그 모델의 공식 정가	내장 비용표가 모델 이름을 알아볼 때
3	내가 짝지어 둔 모델의 정가	클라우드 배포명처럼 모델명이 안 담긴 경우
4	100만 토큰당 5달러 / 25달러	앞의 셋에 다 걸리지 않는 모델

마지막 칸에 붙은 설명이 "자리를 못 찾은 ID라도 절대 공짜로 세지 않는다"입니다. 즉 모르는 모델을 붙이면 안 세는 게 아니라 비싼 쪽으로 셉니다. 실제 단가가 그보다 싸도요. 부팅할 때와 실행 중 ID마다 한 번씩 경고를 띄워준다니, 로그를 보면 알 수는 있습니다.

상한이 안 걸리는 순간이 기본값입니다

차단 판정은 매 요청마다 데이터베이스를 한 번 조회해서 합니다. 이 조회에 2초 제한이 걸려 있는데, 문제는 그 안에 응답이 안 오면 어떻게 하느냐입니다.

⚠️ 기본값은 "그냥 통과시킨다"입니다

집계 저장소가 안 읽히거나 2초를 넘기면, 요청은 그대로 통과되고 경고 한 줄만 로그에 남습니다. 남은 한도를 알려주는 응답 헤더도 이때는 안 붙습니다. 반대로 막고 싶으면 설정에서 실패 시 차단 쪽으로 바꿔야 하는데, 그러면 같은 차단 메시지가 나오되 언제 풀리는지는 안 알려줍니다. 알 방법이 없으니까요.

문서는 이 선택을 숨기지 않고 저울로 설명합니다 — 통과 쪽은 저장소 장애가 서비스 장애로 번지는 걸 막고, 차단 쪽은 집계 안 된 지출이 절대 없다는 걸 보장합니다. 어느 쪽이 옳다고 하지 않습니다. 다만 고르지 않으면 "돈이 새는 쪽"이 자동으로 선택된다는 건 알고 있어야겠죠. 지출 상한을 거는 법을 정리했던 글에서 "상한은 곧 멈추는 날짜"라고 썼는데, 여기엔 멈추지 않는 조건이 하나 더 있었던 셈입니다.

일일 상한은 한국시간 오전 9시에 리셋됩니다

리셋 시점은 전부 UTC 달력 경계 기준입니다. 한국은 아홉 시간 빠르니 그대로 옮기면 이렇게 됩니다. 별것 아닌 것 같지만, "오늘치를 다 썼다"는 감각이 밤 열두 시가 아니라 다음 날 오전 업무 시작 무렵에 풀린다는 뜻이라 체감이 꽤 다릅니다.

기간	문서 표기	한국시간
일별	매일 자정 UTC	매일 오전 9시
주별	월요일 자정 UTC	월요일 오전 9시
월별	1일 자정 UTC	1일 오전 9시

세 기간은 각각 독립적으로 강제됩니다. 하나라도 넘으면 막힙니다. 그리고 여러 개를 동시에 넘겼을 때는 가장 늦게 풀리는 것을 안내해 줍니다. 예외가 딱 하나 있는데, 토큰 개수만 세는 요청은 절대 안 막습니다 — 그건 공짜라서요.

그룹 상한은 나눠 쓰는 예산이 아닙니다

헷갈리기 딱 좋은 지점이라 문서가 먼저 못을 박습니다 — 그룹이나 조직에 건 금액은 "1인당 기본값"이지 여럿이 나눠 쓰는 공동 지갑이 아닙니다. 팀에 월 500달러를 걸었다면 팀 전체가 500달러가 아니라 팀원 각자가 500달러입니다. 열 명이면 5,000달러죠.

적용 순서는 개인 값 → 소속 그룹 중 가장 빡센 값 → 조직 기본값 → 무제한입니다. 여러 그룹에 걸쳐 있으면 기본은 제일 낮은 쪽이 이깁니다. 설정 한 줄로 가장 높은 쪽이 이기게 뒤집을 수도 있는데, 이건 취향이 아니라 정책 결정에 가깝습니다. 계약직에게 빡센 그룹을 하나 더 붙여 조이는 운영이 전자에서만 동작하니까요.

🔔 경고는 양쪽 버전이 다 맞아야 보입니다

한도의 75%와 95%를 넘으면 경고가 뜹니다. 그런데 조건이 둘입니다 — 회사가 돌리는 게이트웨이 서버가 특정 버전 이상이어야 남은 한도가 응답 헤더에 실리고, 개발자 컴퓨터의 도구도 같은 버전 이상이어야 그 헤더를 읽어 경고를 띄웁니다. 한쪽만 최신이면 경고 없이 조용히 막히는 날이 옵니다. 옛 버전에서는 차단 메시지에 기간도, 언제 풀리는지도 안 적혀 있었고요. 그리고 이건 알아두면 좋습니다 — 게이트웨이는 모델 회사가 보내준 원래 한도 헤더를 지우고 안 넘깁니다. 그건 회사 전체의 공용 한도라, 개인에게 보여주면 오해를 부르니까요.

누가 돈을 내는지가 설정 한 줄로 갈립니다

이건 상한 문서가 아니라 옆 문서에서 찾은 건데, 같이 알아야 말이 됩니다. 게이트웨이를 거칠 때 개인 구독이 쓰이느냐 회사 계정이 청구되느냐가 설정 방식에 따라 갈립니다.

설정 방식	개인 구독	청구되는 곳
게이트웨이에 로그인하거나 전용 토큰을 넣음	꺼짐	회사 계정, 종량제 요율
주소만 바꾸고 자격증명은 안 넣음	그대로 유지	내 구독 한도가 그대로 적용

같은 서버를 거치는데 자격증명을 넣었느냐 안 넣었느냐로 누가 돈을 내는지가 통째로 바뀝니다. 회사 상한을 걸어놨는데 아무도 안 걸린다면 이 경우를 의심해 볼 만합니다 — 구독으로 돌고 있으면 게이트웨이의 지출 상한이 잡을 게 없으니까요. 구독 한도가 남아 있어도 크레딧에서 먼저 빠지던 이야기와 같은 종류의 함정입니다. 어느 지갑이 열려 있는지를 매번 확인해야 한다는 것요.

🧾 차단당하면 이렇게 생겼습니다

상한을 넘기면 429 응답이 오는데, 종류가 결제 관련 오류로 찍히고 "다시 시도하지 말 것" 표시가 함께 붙습니다. 메시지에는 어느 기간을 넘겼는지와 리셋 시각이 들어가고, 남은 초까지 헤더로 옵니다. 비슷하게 생긴 한도 초과 에러 일곱 개를 갈라봤던 글에 여덟 번째를 더해야겠습니다. 앞의 일곱 개와 결정적으로 다른 점은 이건 모델 회사가 아니라 우리 회사가 건 벽이라, 기다려도 안 풀리고 관리자가 올려줘야 풀린다는 것입니다.

🧾 정직하게 — 이 글의 한계

• 직접 세워보고 쓴 글이 아닙니다. 게이트웨이는 서버와 데이터베이스가 필요해서, 이 글은 문서를 읽고 정리한 것입니다. 실제 동작이 문서와 다를 여지는 남습니다.
• 개인 사용자에게는 해당 없는 이야기입니다. 혼자 쓰는 구독에는 이런 상한을 걸 수 없고, 제가 찾아본 범위에서는 여전히 개인용 금액 상한 스위치는 없습니다.
• 금액은 견적이지 청구서가 아닙니다. 문서가 직접 "차단기이지 인보이스가 아니다"라며 실제 청구는 공급사 리포트와 대조하라고 적어놨습니다. 그러니 여기 숫자로 정산하면 안 됩니다.
• 버전에 따라 동작이 다릅니다. 세 개의 서로 다른 버전 경계가 나오는데, 이 글은 최신 기준으로 적었습니다. 옛 버전은 메시지도 요율 결정 방식도 다릅니다.

🗺️ AI 지출 전체 지도

상한은 마지막 방어선이지 첫 단추가 아닙니다. 그 앞에 구독과 종량제 중 무엇을 고를지, 캐시를 어떻게 쓸지, 모델을 어떻게 섞을지가 먼저 있고요. 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

🔁 상한에 부딪히기 전에 미리 재는 길

상한을 거는 법은 위에서 봤지만, 이 글에 없는 각도가 하나 있습니다 — 보내기 전에 얼마짜리 요청인지 미리 아는 것입니다. 토큰을 미리 세는 창구는 공짜인 데다 실제 호출 한도를 전혀 갉아먹지 않아서, 큰 요청을 앞단에서 걸러내는 문지기로 세워도 서비스가 느려지지 않습니다. 상한에 걸려 끊기고 그 값까지 청구되는 상황 자체를 만들지 않는 쪽이 낫습니다.

자주 묻는 것

Q. 개인이 쓰는 구독에도 이렇게 상한을 걸 수 있나요?

못 겁니다. 이 기능은 회사가 게이트웨이 서버를 직접 돌릴 때만 쓸 수 있습니다. 개인은 여전히 사용량을 보는 것까지고, "이 금액을 넘으면 멈춰라"를 거는 방법은 제가 찾은 범위에서는 없습니다. 종량제 계정이라면 결제 쪽 예산 알림이 있긴 하지만 그건 알림이지 차단이 아닙니다.

Q. 퇴사자 기록은 어떻게 되나요?

보관 기간이 일부러 다르게 설계돼 있습니다. 이름·이메일·소속 그룹처럼 사람을 식별하는 정보는 마지막 활동 후 90일이 기본이고, 금액 집계는 13개월이 기본입니다. 문서 설명이 명쾌합니다 — 신원은 갱신이 끊기면 늙어 사라지고, 익명화된 지출 숫자는 연간 비교용으로 남는다는 것요. 당장 지워야 하면 데이터베이스에서 해당 행을 직접 지우라고 안내합니다.

Q. 관리 화면에서 조회할 때 주의할 게 있나요?

문서가 스스로 경고를 답니다. 사용자를 이름·이메일로 검색하는 값이 주소창 뒤에 붙어서 가는 구조라, 중간에 있는 프록시나 로드밸런서의 접속 로그에 그 값이 그대로 남습니다. 개인정보 로그 정책이 빡센 곳이면 거기서 지우라고 안내하고요. 자기 API 설계의 약점을 문서에 적어두는 건 흔치 않습니다.

✨ 오늘 확인한 것 정리

사람별 금액 상한을 실제로 강제하는 공식 경로가 있었습니다 — 다만 회사가 게이트웨이를 직접 돌려야 하고, 일·주·월이 각각 따로 걸립니다. 예상 밖이었던 셋은 중간에 끊어도 청구된다는 것, 모르는 모델은 비싼 요율로 센다는 것, 그리고 집계 DB가 안 읽히면 기본값이 그냥 통과라는 것입니다. 마지막 하나는 고르지 않으면 새는 쪽이 선택된다는 뜻이라, 도입한다면 이 설정부터 보시길.

※ 확인 경로(2026년 8월 16일 기준): code.claude.com/docs/en/claude-apps-gateway-spend-limits 및 code.claude.com/docs/en/gateways. 우리말 표현과 한국시간 환산은 제가 옮긴 것입니다.

※ 버전에 따라 메시지와 헤더가 다릅니다. 금액은 견적이며 실제 청구는 공급사 리포트와 대조해야 합니다.