Claude 프롬프트 캐시, 1,024토큰 미만에서는 조용히 실패

Claude 프롬프트 캐싱은 모델별 최소 접두사(512~4,096토큰)가 필요하며, 이보다 짧으면 캐시도 오류도 없습니다

Aug 05, 2026

Claude API의 프롬프트 캐싱은 에이전트 루프 비용을 $50에서 $5로 낮출 수도 있습니다. 단, 실제로 캐시가 만들어질 때만 그렇습니다. 캐시가 만들어지지 않는 가장 흔한 이유는 아무 오류 메시지도 내지 않는 최소 기준값입니다.

달라진 점: 자동 캐싱과 진단, 그리고 아무도 알려주지 않는 최소 기준

Claude의 프롬프트 캐시에는 캐시 가능한 최소 prefix가 있으며, 이는 전체에 적용되는 단일 숫자가 아니라 모델별로 다릅니다. Opus 5, Fable 5, Mythos 5는 512토큰, Opus 4.8, Sonnet 5, Sonnet 4.6/4.5, Opus 4.1/4는 1,024토큰, Opus 4.7은 2,048토큰, Opus 4.6, Opus 4.5, Haiku 4.5는 4,096토큰입니다 . 이 기준보다 짧으면 아무것도 캐시되지 않고 예외도 발생하지 않습니다. 요청은 전체 입력 요율로 과금되며, 유일한 신호는 두 캐시 토큰 카운터가 모두 0으로 남는 것입니다 .

2026년에 있었던 두 가지 플랫폼 변경으로 이 문제를 더 쉽게 잡아낼 수 있게 됐습니다. 2026년 2월 19일, Messages API에서 자동 캐싱이 GA로 제공되기 시작했습니다. 최상위 cache_control 필드 하나가 마지막 캐시 가능 블록에 breakpoint를 두고, 대화가 길어질수록 이를 앞으로 이동시킵니다 . 2026년 5월 13일에는 캐시 진단이 공개 베타로 들어왔습니다. cache-diagnosis-2026-04-07 헤더를 사용하면 요청이 조용히 지나가는 대신 cache_miss_reason을 반환합니다 . 두 변경 모두 토큰 최소 기준을 없애지는 않습니다. 단지 보이게 만들어줄 뿐입니다.

프로덕션에서 쓰기 전에 확인할 것

Screenshot of https://code.claude.com/docs/en/prompt-caching

캐싱 숫자가 움직이려면 세 가지가 먼저 갖춰져야 합니다. cache_control 블록을 지원하는 Messages API 접근 권한, 안정적으로 반복되는 콘텐츠가 최소 캐시 가능 prefix를 실제로 넘기는 모델, 그리고 할인 여부를 믿는 대신 usage 메타데이터를 읽는 습관입니다. 1시간 TTL은 2025년 8월 13일부터 베타 헤더 없이 일반 제공되고 있지만, 대화 중간의 tool 변경에는 여전히 mid-conversation-tool-changes-2026-07-01 헤더가 필요합니다 .

최소 기준은 모델별로 다르며 최대 8배까지 차이 납니다. 그보다 짧은 프롬프트는 marker를 어디에 두든 절대 캐시될 수 없습니다 .

캐시 가능한 최소 prefix	모델
512토큰	Opus 5, Fable 5, Mythos 5
1,024토큰	Opus 4.8, Sonnet 5, Sonnet 4.6 / 4.5, Opus 4.1 / 4
2,048토큰	Opus 4.7
4,096토큰	Opus 4.6, Opus 4.5, Haiku 4.5

정답은 usage 안에 있습니다. cache_creation_input_tokens(ephemeral_5m_input_tokens와 ephemeral_1h_input_tokens로 나뉨)와 cache_read_input_tokens를 확인하세요. marker 예산도 계산해야 합니다. 요청 하나에는 명시적 cache_control breakpoint를 최대 네 개까지 담을 수 있고, 자동 캐싱도 그 슬롯 하나를 사용합니다. 따라서 자동 캐싱과 수동 marker 네 개를 함께 쓰면 400이 반환됩니다 .

캐시가 실제로 생성됐는지 확인하는 방법

캐시가 생성됐는지 확인하려면 한 번 측정하고 한 번 반복하면 됩니다. cache_control 중단점 앞에 정확히 놓인 콘텐츠의 토큰 수를 세고, 그 수가 모델의 최소 기준을 넘는지 비교한 다음, 동일한 요청을 두 번 보내 첫 번째 호출에서는 usage.cache_creation_input_tokens를, 두 번째 호출에서는 usage.cache_read_input_tokens를 확인하세요. 그 밖의 것들, 예를 들어 더 낮은 input_tokens 값이나 더 빠른 응답은 정황 증거일 뿐입니다. 모델 하한선보다 낮으면 아무것도 캐시되지 않으며 오류도 발생하지 않습니다 .

마커를 어디에 두느냐가 무엇이 계산되는지를 결정합니다. 전체 도구 접두부를 캐시하려면 tools 배열의 마지막 항목에, 도구가 없다면 정적 시스템 프롬프트의 끝에 마커를 두세요. mcp_toolset의 경우에는 중단점이 마지막으로 확장된 도구에 걸리도록 toolset 항목에 표시합니다 .

아래 스니펫은 예시입니다. 실제 ANTHROPIC_API_KEY가 필요하므로 실행하지 않았습니다. 1,024토큰 미만 블록에 일부러 마커를 붙여 두 카운터가 모두 비어 돌아오는 것을 확인할 수 있게 했습니다:

import json
import os
import sys
import urllib.request

key = os.environ.get("ANTHROPIC_API_KEY")
if not key:
    sys.exit("needs ANTHROPIC_API_KEY")

body = {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "This cacheable block is intentionally below 1,024 tokens.",
                    "cache_control": {"type": "ephemeral"},
                },
                {"type": "text", "text": "\nReply with OK."},
            ],
        }
    ],
}

req = urllib.request.Request(
    "https://api.anthropic.com/v1/messages",
    data=json.dumps(body).encode(),
    headers={
        "content-type": "application/json",
        "anthropic-version": "2023-06-01",
        "x-api-key": key,
    },
)

with urllib.request.urlopen(req, timeout=30) as r:
    data = json.load(r)

usage = data["usage"]
print("cache_creation_input_tokens =", usage.get("cache_creation_input_tokens"))
print("cache_read_input_tokens =", usage.get("cache_read_input_tokens"))
print("No error is raised; sub-1024-token prompt cache is just not used.")

두 번째 호출에서도 두 카운터가 모두 0이면 접두부가 하한선보다 짧은 것입니다. 정적 콘텐츠를 더 붙이거나, 더 많은 안정적인 내용을 마커 앞쪽으로 옮기세요. 가끔만 0이 나온다면 추측을 멈추고 2026년 5월 13일 공개 프리뷰에 들어간 diagnostics beta를 사용하세요. diagnostics.previous_message_id와 함께 cache-diagnosis-2026-04-07 헤더를 보내면, 응답의 cache_miss_reason이 이전 턴과 접두부가 처음 달라진 지점을 알려줍니다 .

그다음에는 계속 지켜봐야 합니다. Anthropic의 Claude Code 팀은 히트율을 회계 항목이 아니라 신뢰성 신호로 봅니다:

"We run alerts on our prompt cache hit rate and declare SEVs if they're too low… monitor your cache hit rate like you monitor uptime." — Anthropic Claude Code 팀 (source: Claude Code를 만들며 얻은 교훈)

생성 카운터와 읽기 카운터는 모델, TTL, 워크플로별로 나누어 따로 기록하세요. 단일 집계 숫자는 가장 중요한 경우를 숨깁니다. 매 호출마다 접두부가 쓰이지만 한 번도 읽히지 않는 경우입니다.

캐시가 생성된 뒤에 드러나는 함정

생성된 캐시가 곧 안정적인 캐시는 아닙니다. 접두부가 히트하기 시작하면, 그다음 실패 유형은 캐시한 내용을 조용히 다시 쓰거나 무효화하는 설정 플래그와 서버 측 동작에서 나옵니다. 가장 흔한 의외의 상황은 이렇습니다. 요청에 이미 cache_control 마커가 있고 Claude가 웹 검색, 웹 가져오기, 코드 실행 같은 서버 도구를 호출하면, API는 다음 반복 전에 서버 도구 결과에 자동으로 중단점을 삽입합니다. 이 중단점은 사용자가 둔 마커와 관계없이 항상 5분 TTL을 사용합니다 . 따라서 1시간 전용 구성에서도 ephemeral_5m_input_tokens 쓰기가 보고됩니다. 이는 예상된 동작이며 누수가 아닙니다.

명시적으로 로그에 남길 만한 무효화 트리거는 다음과 같습니다:

tool_choice 또는 disable_parallel_tool_use를 변경하면 messages 캐시가 무효화됩니다 .
웹 검색이나 citations를 켜고 끄면 system과 messages가 모두 무효화됩니다 .
thinking 매개변수나 output_config.effort를 변경하면 모든 모델에서 messages가 무효화됩니다. 또한 해당 설정을 tools와 system보다 앞서 렌더링하는 모델에서는 tools와 system도 함께 무효화됩니다 .

TTL을 섞어 쓰는 것은 허용되지만 순서는 엄격합니다. 1시간 블록은 반드시 5분 블록보다 앞에 와야 합니다. 과금은 세 위치를 기준으로 계산됩니다. 가장 높은 캐시 히트 지점(A), 그 뒤의 마지막 1시간 중단점(B), 마지막 중단점(C)입니다. A에는 읽기 비용이, B−A에는 1시간 쓰기 비용이, C−B에는 5분 쓰기 비용이 부과됩니다 . 이 순서를 뒤집으면 실제 지불 금액을 설명하는 계산이 더 이상 성립하지 않습니다.

다음에 해볼 것: 진단, 킵얼라이브, 손익분기 계산

How to Confirm Your Cache Actually Formed

먼저 성능이 가장 나쁜 호출 경로에 진단 베타를 적용하세요. cache-diagnosis-2026-04-07 헤더를 사용하면 요청에서 diagnostics.previous_message_id를 전달하고, 이전 턴과 prefix가 처음 달라진 지점을 가리키는 cache_miss_reason을 받을 수 있습니다 — 30KB prefix를 손으로 이분 탐색하는 대신 바로 답을 얻는 셈입니다.

그다음 TTL을 넓히기 전에 계산부터 확인하세요. 5분 write는 기본 입력 비용의 1.25배, read는 0.1배이므로 warm prefix에서 두 번 호출하면 캐시가 없을 때의 2배가 아니라 1.35배가 듭니다 — 두 번째 read에서 비용을 회수합니다. 1시간 write는 2.0배라서 대략 두세 번의 read가 있어야 손익분기를 넘습니다 . 킵얼라이브 ping으로 prefix를 warm 상태로 유지할 계획이라면, Khailo의 2026년 7월 24일 논문은 측정된 provider 파라미터 기준으로 5분 tier는 약 46분, 1시간 tier는 3.3시간 정도의 손익분기 시간을 도출합니다 .

마지막으로 알아둘 기본값이 하나 더 있습니다. Claude Code 클라이언트는 구독에서는 1시간 TTL을 자동으로 요청하지만, API key에서는 ENABLE_PROMPT_CACHING_1H=1을 설정하지 않으면 5분으로 fallback합니다 . 결론은 좁고 검증 가능합니다. 모델과 workflow별로 cache_creation_input_tokens와 cache_read_input_tokens를 로깅하고, 둘 다 계속 0이라면 조용히 비용을 계속 내는 상태가 아니라 결함 리포트로 다루세요.

자주 묻는 질문

Claude가 실제로 캐시하는 가장 작은 프리픽스는 어느 정도인가요?

모델에 따라 다르며 차이가 큽니다. Opus 5, Fable 5, Mythos 5는 512토큰, Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5, Opus 4.1, Opus 4는 1,024토큰, Opus 4.7은 2,048토큰, Opus 4.6, Opus 4.5, Haiku 4.5는 4,096토큰입니다 . 이 하한은 버전이 올라간다고 항상 커지거나 작아지는 식으로 단조롭지 않습니다. Opus 4.8은 1,024로 내려가 Opus 4.7의 2,048보다 낮아졌습니다 . 짧은 시스템 프롬프트도 당연히 캐시될 것이라고 보기 전에, 실제 배포할 정확한 모델의 기준값을 확인하세요.

프롬프트 캐시가 실제로 만들어졌는지 어떻게 확인하나요?

API 응답에서 두 필드, usage.cache_creation_input_tokens와 usage.cache_read_input_tokens를 확인하면 됩니다. creation 값이 0이 아니면 프리픽스가 기록된 것이고, read 값이 0이 아니면 재사용된 것입니다. 둘 다 0이면 input_tokens가 아무리 크게 보여도 아무것도 캐시되지 않은 것입니다. 전체 입력은 read + creation + input이므로, input_tokens 값은 큰데 캐시 카운터가 계속 0이라면 바로 그게 실패 신호입니다 . TTL 단위로 기록량을 나눠 봐야 한다면 cache_creation 객체에서 쓰기 토큰이 ephemeral_5m_input_tokens와 ephemeral_1h_input_tokens로 분리됩니다.

프리픽스가 너무 짧아 캐시할 수 없으면 API가 오류를 내나요?

아니요. 기준보다 짧은 프리픽스에 cache_control 마커를 붙여 요청해도 요청은 정상적으로 성공하고, 전체 입력 요율로 과금됩니다. 경고도, 예외도, 헤더도 없습니다. 관측 가능한 유일한 신호는 두 캐시 토큰 카운터가 모두 0으로 유지되는 것입니다 . 그래서 Claude Code 팀은 캐시 적중률을 단순 최적화 세부사항이 아니라 운영 지표로 다룹니다. 프롬프트 캐시 적중률에 알림을 걸고, 떨어지면 SEV를 선언합니다 .

5분 TTL과 1시간 TTL 중 무엇을 써야 하나요?

활발한 채팅 루프, 짧은 도구 사용 구간, 재시도에는 5분 티어를 쓰세요. 쓰기는 기본 입력의 1.25배, 읽기는 0.1배라서 캐시하지 않은 호출을 두 번 하는 경우와 비교하면 두 번째 사용부터 손익분기점을 넘습니다 . 1시간 티어는 쓰기가 2.0배이므로, 비싼 컨텍스트 설정을 긴 작업이나 여러 워커 호출에서 반복해서 읽을 때만 쓰는 편이 좋습니다. 대략 두세 번 읽어야 비용을 회수합니다 . keepalive ping으로 프리픽스를 따뜻하게 유지한다면 측정된 손익분기 시간은 5분 티어가 약 46분, 1시간 티어가 약 3.3시간입니다 . TTL을 섞어 쓸 수는 있지만, 1시간 블록은 5분 블록보다 앞에 있어야 합니다.

1시간 전용 캐시 설정인데 왜 5분 쓰기가 보이나요?

서버 도구가 자체 중단점을 삽입하기 때문입니다. 요청에 이미 cache_control 마커가 있고 Claude가 웹 검색, 웹 가져오기, 코드 실행 같은 서버 도구를 호출하면, API는 다음 반복 전에 서버 도구 결과에 자동으로 중단점을 추가합니다. 이 중단점은 사용자가 설정한 마커와 관계없이 항상 5분 TTL을 사용합니다 . 그래서 1시간 전용이라고 생각한 설정에서도 ephemeral_5m_input_tokens 쓰기가 보고됩니다. 이는 문서화된 동작이지 결함이 아닙니다. 디버깅할 문제가 아니라 예산에 반영할 항목입니다.

대화 중간에 도구를 추가하거나 제거해도 캐시가 유지되나요?

최신 모델에서는 옵트인 헤더를 쓰면 가능합니다. 2026년 7월 24일부터 mid-conversation-tool-changes-2026-07-01 헤더를 사용하면 Fable 5, Mythos 5, Opus 4.8, Opus 5에서 턴 사이에 도구를 추가하거나 제거해도 캐시를 유지할 수 있습니다. 2026년 5월 28일의 관련 변경으로 대화 중간의 role: "system" 메시지도 허용되어, 프리픽스를 무효화하지 않고 지시사항을 바꿀 수 있습니다 . 구형 모델에서는 도구 검색 도구와 함께 defer_loading을 쓰는 것이 구조적인 해결책입니다. 지연된 정의는 프리픽스에 들어가지 않고, 발견된 도구는 대화 안에 tool_reference 블록으로 추가됩니다 .

현실적인 비용 절감 폭은 어느 정도인가요?

독립 측정치는 벤더가 제시한 대표 수치보다 낮게 나옵니다. Anthropic의 최초 발표는 길고 반복되는 프롬프트에서 최대 90% 비용 절감과 85% 지연 시간 감소를 언급했습니다 . 반면 DeepResearch Bench에서 세 벤더를 대상으로 10,000토큰 시스템 프롬프트를 사용하는 500개 이상의 에이전트 세션을 평가한 연구는 41~80% 비용 절감과 13~31% time-to-first-token 개선을 보고했습니다 . 이 논문은 단순히 전체 컨텍스트를 캐시하면 지연 시간이 늘어날 수 있다는 점도 확인했습니다. 가장 일관된 전략은 안정적인 시스템 컨텍스트를 캐시하고, 변동성이 큰 도구 결과는 재사용 프리픽스 밖에 두는 것이었습니다.