프롬프트 캐싱은 조용히 실패합니다 — 에러도 안 납니다

프롬프트 캐싱 · 비용

캐시를 켰는데
안 켜졌습니다.

문서에 이렇게 적혀 있습니다 — "에러는 반환되지 않습니다." 최소 길이에 못 미치면 캐시 표시를 해둬도 그냥 안 걸리고, 아무 말 없이 정가로 청구됩니다.

앞 글에서 캐시에서 읽은 토큰이 한도에서 빠진다는 걸 봤습니다. 그럼 캐시를 켜면 무조건 이득인가. 가격 문서를 열어보니 그렇게 단순하지 않았습니다.

📌 30초 요약

• 캐시에서 읽으면 0.1배. 90퍼센트 싸집니다.
• 그런데 쓸 때는 1.25배(5분) 또는 2배(1시간)입니다. 정가보다 비쌉니다.
• 그래서 몇 번 재사용하느냐가 본전을 가릅니다. 계산해뒀습니다.
• ⚠️ 최소 길이에 못 미치면 캐시가 안 걸립니다. 그런데 에러가 안 납니다.
• 브레이크포인트는 최대 4개, 위쪽이 바뀌면 아래 캐시가 전부 무효가 됩니다.

① 읽기는 확실히 쌉니다 — 0.1배

먼저 좋은 소식입니다. 문서가 배수를 명시합니다.

구분	기본 입력가 대비
5분 캐시 쓰기	1.25배
1시간 캐시 쓰기	2배
캐시 읽기	0.1배

읽기가 10분의 1이라는 건 큽니다. 시스템 프롬프트가 길거나 문서를 통째로 물고 다니는 구조라면 여기서 대부분의 비용이 빠집니다. 문제는 쓰기가 정가보다 비싸다는 점입니다.

② 몇 번 써야 본전인가 — 계산해봤습니다

같은 내용을 N번 보낸다고 하고, 캐시를 안 쓸 때와 쓸 때를 비교했습니다. 캐시를 쓰면 첫 번째는 쓰기(비쌈), 나머지는 읽기(쌈)가 됩니다.

# 기본 입력가를 1로 두고, 같은 내용을 N번 보낼 때
캐시 안 씀   = N
5분 캐시     = 1.25 + 0.1 x (N-1)
1시간 캐시   = 2.00 + 0.1 x (N-1)

재사용 횟수	캐시 안 씀	5분 캐시	1시간 캐시
1번 (재사용 없음)	1.00	1.25 손해	2.00 손해
2번	2.00	1.35 이득	2.10 손해
3번	3.00	1.45	2.20 이득
10번	10.00	2.15	2.90
100번	100.00	11.15	11.90

💡 읽는 법

5분 캐시는 두 번째 재사용부터 이득입니다. 문턱이 아주 낮습니다.

1시간 캐시는 세 번째부터입니다. 두 번만 쓸 거면 오히려 5퍼센트쯤 손해입니다.

100번 재사용하면 비용이 9분의 1 수준으로 떨어집니다. 반복 호출이 많은 구조일수록 효과가 커집니다.

⚠️ 위 표는 제가 계산한 것입니다

문서에 있는 건 배수 세 개(1.25 · 2 · 0.1)뿐입니다. 표의 숫자는 그 배수로 제가 산수한 결과이고, 모든 요청이 캐시에 정확히 적중한다는 가정이 깔려 있습니다. 실제로는 만료·무효화 때문에 중간에 다시 쓰기가 발생하고, 그때마다 1.25배가 또 붙습니다. 그러니 이 표는 상한선이지 실측이 아닙니다.

③ 여기가 진짜 함정입니다 — 조용히 실패합니다

캐시에는 최소 길이가 있습니다. 그보다 짧으면 캐시 표시를 해둬도 안 걸립니다. 문제는 그다음 문장입니다.

📄 원문

"Prompts shorter than the minimum cannot be cached, even if marked with cache_control. No error is returned; check response usage fields to verify caching occurred."

→ 에러가 안 납니다. 캐시를 켰다고 생각하고 몇 달을 돌렸는데 실제로는 한 번도 안 걸렸을 수 있습니다. 응답의 사용량 필드를 직접 봐야 압니다.

최소 길이는 모델마다 다릅니다. 최대 8배까지 차이가 납니다.

최소 토큰	해당 모델
512	Opus 5 · Fable 5 · Mythos 5
1,024	Opus 4.8 · Sonnet 5 · Sonnet 4.6/4.5 · Opus 4.1 · Opus 4
2,048	Mythos Preview · Opus 4.7 · Haiku 3.5
4,096	Opus 4.6 · Opus 4.5 · Haiku 4.5

여기서 사고가 납니다. 싸다고 Haiku 4.5로 갈아탔는데 최소 길이가 4,096이라, 1,024로 잘 돌던 캐시가 조용히 안 걸리게 됩니다. 모델을 바꾸면 캐시 동작도 바뀝니다. 에러가 없으니 청구서로만 알게 됩니다.

④ 위가 바뀌면 아래가 다 날아갑니다

캐시는 계층 구조입니다. 문서가 순서를 명시합니다 — 도구 정의 → 시스템 → 대화. 위쪽이 바뀌면 그 아래가 전부 무효가 됩니다.

이걸 바꾸면	무효화되는 범위
도구 정의	전부 (도구·시스템·대화)
웹검색 켜고 끄기	시스템 · 대화
인용 기능 켜고 끄기	시스템 · 대화
속도 설정	시스템 · 대화
도구 선택 방식	대화
이미지 추가	대화

도구를 하나 추가하는 순간 시스템 프롬프트 캐시까지 통째로 날아갑니다. 개발 중에 도구 목록을 자주 손대면 캐시가 계속 다시 써지고, 그때마다 1.25배가 붙습니다. "캐시를 켰는데 왜 안 싸지지"의 상당수가 여기입니다.

그리고 브레이크포인트는 최대 4개입니다. 자동 캐싱이 켜져 있으면 그중 한 자리를 자동으로 씁니다. 이미 4개를 직접 지정해뒀다면 400 오류가 납니다 — 이건 조용히 실패하지 않고 에러로 알려주는 쪽입니다.

⑤ 걸렸는지 확인하는 법 — 필드 세 개

문서가 "응답의 사용량 필드를 확인하라"고 했으니, 그 필드가 뭘 뜻하는지 정리합니다.

# 응답 usage 안을 보세요
cache_creation_input_tokens   # 캐시에 써 넣은 양 (1.25배 또는 2배)
cache_read_input_tokens       # 캐시에서 읽은 양 (0.1배) ← 이게 0이면 안 걸린 것
input_tokens                  # 캐시 지점 이후의 새 입력분

🧭 30초 점검

1. 같은 요청을 연달아 두 번 보냅니다.

2. 첫 번째 응답에 cache_creation_input_tokens가 0보다 큰지 봅니다. 0이면 최소 길이 미달입니다.

3. 두 번째 응답에 cache_read_input_tokens가 0보다 큰지 봅니다. 0이면 무효화됐거나 만료된 겁니다.

🚫 이 글이 확인하지 못한 것

저는 실제로 API를 호출해보지 않았습니다. 위 점검 순서는 문서가 안내한 필드를 바탕으로 제가 정리한 것이고, 제 계정에서 돌려 확인한 결과가 아닙니다.

그리고 이건 한 회사의 API 문서입니다. 다른 제공사의 캐싱은 배수도 최소 길이도 다릅니다. 여기 숫자를 그대로 옮겨 쓰지 마세요. 구독 요금제(웹·앱)에는 이 배수가 적용되지 않습니다 — 그쪽은 한도 방식으로 돌아갑니다.

자주 묻는 것

Q. 5분과 1시간 중 뭘 골라야 하나요?

재사용 간격으로 정하세요. 5분 안에 다시 부를 구조면 5분이 쌉니다. 간격이 그보다 길면 5분짜리는 만료돼서 다시 쓰기(1.25배)가 반복되니, 그럴 땐 1시간이 낫습니다. 다만 1시간은 세 번은 써야 본전입니다.

Q. 캐시 시간은 언제부터 세나요?

문서에 따르면 응답이 끝난 시점이 아니라 요청이 시작된 시점부터입니다. 응답이 오래 걸리는 작업이라면 체감 유효시간이 그만큼 줄어듭니다.

Q. 대화가 길어지면 캐시가 도움이 되나요?

구조상 그렇습니다 — 앞부분이 고정돼 있으면 그 부분은 계속 읽기로 처리되니까요. 다만 대화 중간에 이미지를 넣거나 도구를 바꾸면 그 아래가 무효화됩니다. 위 표를 참고하세요.

📌 보탬 (8월 13일) — 배치와 겹쳐 쓰면 할인이 쌓입니다

캐싱 할인은 배치 처리 할인(50퍼센트)과 중첩됩니다. 다만 배치 안에서는 캐시 예열이 지원되지 않습니다 — 배치 도중 쓴 임시 캐시가 후속 요청 전에 만료될 가능성이 크기 때문입니다. 그래서 문서는 배치와 함께 쓸 땐 1시간 캐시를 권합니다. 위에서 계산한 "1시간짜리는 세 번은 써야 본전"이라는 조건은 배치라면 자연히 채워집니다 → 배치로 절반 값에 씁니다

📌 보탬 (8월 14일) — 같은 구조를 보안 쪽에서도 봤습니다

캐싱은 최소 길이에 못 미치면 에러 없이 안 걸린다고 적었습니다. 에이전트 샌드박스에도 같은 형태가 있었습니다 — 의존 패키지가 없거나 플랫폼이 미지원이면 경고만 띄우고 샌드박스 없이 실행되는 게 기본값입니다. 안전장치일수록 "실패했을 때 어떻게 되는지"를 먼저 봐야 한다는 게 두 사례의 공통점입니다 → 샌드박스를 켰는데 안 켜졌을 수 있습니다

📌 보탬 (8월 14일) — 캐시 수명이 조건에 따라 12분의 1로 줄어듭니다

이 글은 캐시가 걸렸는지를 다뤘는데, 얼마나 오래 유지되는지에 조건이 붙어 있었습니다. 구독 플랜은 1시간이지만 사용량 크레딧으로 넘어가는 순간 5분으로 떨어집니다. API 키·클라우드 제공사도 기본 5분입니다. 한도를 넘긴 뒤 띄엄띄엄 쓰면 매번 전체 컨텍스트를 캐시 없이 재처리하게 됩니다 → 첫 글자를 치기 전에 이미 8,520 토큰

✨ 정리하면

읽기는 0.1배지만 쓰기는 1.25~2배입니다. 5분 캐시는 두 번째부터, 1시간 캐시는 세 번째부터 이득입니다.

그리고 최소 길이에 못 미치면 에러 없이 그냥 안 걸립니다. 모델을 바꿨을 때가 특히 위험합니다 — 512에서 4,096까지 차이가 나니까요.

같은 요청을 두 번 보내고 응답 필드 두 개만 보세요. 30초면 켜졌는지 알 수 있습니다.

🧭 AI 지출 전체 그림

이 글은 API 캐싱 비용 한 지점만 다뤘습니다. 개인·개발자·회사로 나눠 돈이 어디서 새는지 묶어둔 허브가 있습니다 → AI에 쓰는 돈 총정리 — 숨은 비용 7가지

🔗 같이 보면 좋은 글

• 사용량 화면의 숫자가 전부가 아닙니다 — 이 글의 앞 이야기
• 지출 상한 거는 법 — 캐시가 안 걸렸을 때의 방어선
• 에이전트를 여러 개 돌리는 도구 — 병렬이면 토큰도 병렬입니다
• 첫 결제 전에 확인할 것

---

확인 시점 — 2026년 8월 13일 밤. ✅ 1차 확인 : Claude 플랫폼 문서 「Prompt caching」 원문 직접 열람 — 배수 3종(5분 쓰기 1.25배 · 1시간 쓰기 2배 · 읽기 0.1배), 모델별 최소 캐시 토큰 4구간, 브레이크포인트 최대 4개 및 자동 캐싱이 슬롯을 차지하는 동작, 무효화 계층(도구→시스템→대화)과 항목별 영향 범위, TTL 계산 시작 시점, 최소 미달 시 무에러 동작. 인용문은 원문 그대로입니다. 제가 계산한 것 : 본문 ②의 손익분기 표는 문서의 배수만 가지고 직접 산수한 값이며 전량 캐시 적중을 가정합니다. 실제 청구액이 아닙니다. 확인하지 않은 것 : 실제 API 호출로 검증 · 타 제공사의 캐싱 정책 · 구독 요금제에서의 적용 여부. 가격과 최소 토큰은 예고 없이 바뀌고 모델·플랫폼마다 다릅니다. 제휴·협찬 없습니다.