"토큰이 부족합니다" 오류: 의미와 해결 방법

"토큰이 부족합니다"는 하나의 오류가 아닙니다. 사람들은 이 표현을 다섯 가지 다른 문제에 씁니다. 잔액이 비었거나, 요청이 너무 빨리 들어오거나, 키가 틀렸거나, 프롬프트가 모델의 컨텍스트 윈도에 들어가지 않거나, 답변이 출력 한도에 걸려 문장 중간에 끊긴 경우입니다. 각각 해결법이 다르고, 이들을 구분하는 가장 빠른 방법은 메시지 문구가 아니라 HTTP 상태 코드와 오류 본문입니다.

표에서 증상을 찾고, 점검을 실행하고, 해결법을 적용하세요.

"토큰"이 의미할 수 있는 세 가지#

오류 메시지의 이 단어는 세 가지 다른 양을 가리킵니다.

• 잔액. 토큰은 지불하는 대상이므로, "토큰이 떨어졌다"는 종종 "돈이 떨어졌다"는 뜻입니다. 선불 서비스에서는 이것이 잔액입니다.
• 분당 한도. 한도는 요청 수나 분당 토큰 수로 셀 수 있습니다. 하나에 걸리면 해결법은 기다리고 한 번에 덜 보내는 것입니다.
• 윈도 크기. 컨텍스트 윈도는 모델이 한 요청에서 읽을 수 있는 토큰 수로, 프롬프트와 답변을 합친 것입니다.

그리고 절대 의미하지 않는 것 하나: API 키는 토큰 재고가 아닙니다. 키는 계정을 식별합니다. 떨어지는 것은 그 뒤의 잔액이거나 키에 붙은 한도입니다. 단위 자체가 처음이라면 What is a token in AI?부터 보세요.

1. 잔액이 비었음#

DeepSeek의 API 문서는 HTTP 402 Insufficient Balance를 "잔액이 소진되었습니다"로 설명합니다. Claude의 API는 결제 및 지불 문제에 402 billing_error를 사용합니다. 이름은 다르지만 상황은 같습니다: 돈이 없습니다.

CheapTokens도 원칙적으로 같은 방식입니다: 선불 잔액, 사용한 만큼 지불, 모든 모델에 하나의 잔액. 그래서 뭔가 깨지면 먼저 잔액을 보세요. 10초면 되는 점검이고 가장 흔한 원인을 배제합니다.

2. 속도 제한에 걸림#

DeepSeek는 HTTP 429 Rate Limit Reached를 요청이 너무 빨리 오거나 동시성 또는 QPS 한도를 초과한 것으로 문서화합니다. 해결법은 속도를 조절하는 것입니다: 병렬 요청을 줄이고, 엔드포인트를 두들기지 말고 재시도 지연을 늘리세요(1초, 2초, 4초).

함정 하나. Claude의 API는 티어의 월 지출 상한에 도달했을 때도 429 rate_limit_error를 반환하며, 그 응답에는 retry-after 헤더가 없습니다. 그래서 기다려도 풀리지 않는 429는 속도가 아니라 돈 문제일 수 있습니다. 기다려도 도움이 안 되면 원인 1로 돌아가세요.

3. 키가 틀림#

HTTP 401은 두 문서 모두에서 키 문제입니다: DeepSeek는 잘못된 API 키로, Claude는 authentication_error로 나열합니다. 흔한 이유는 키와 함께 복사된 여분의 공백이나 줄바꿈, 삭제되거나 재생성된 키, 잘못된 주소로 보낸 키입니다. 한 서비스의 키는 다른 서비스의 URL에서 작동하지 않습니다. CheapTokens의 base URL은 https://api.cheaptokens.dev/v1입니다.

연결 중에 만날 수 있는 다른 오류는 Common connection errors and how to fix them을 보세요.

4. 프롬프트가 컨텍스트 윈도에 들어가지 않음#

컨텍스트 윈도는 모델이 한 요청에서 읽는 모든 것을 셉니다: 시스템 프롬프트, 전체 대화 이력, 새 메시지, 그리고 답변을 위한 공간. CheapTokens에서 카탈로그 모델들의 윈도는 다음과 같습니다:

채팅은 자체 기억이 없습니다. 클라이언트는 매 요청마다 전체 이력을 다시 보내므로, 각 요청은 이전보다 커집니다. 증가를 보여주는 가상의 채팅입니다(설명을 위한 반올림 수치): 시스템 프롬프트 1,000 토큰, 매 턴마다 질문 약 500 토큰과 답변 1,500 토큰, 합계 2,000 토큰이 더해집니다.

1,000 + 30 × 2,000 = 61,000 토큰

이것이 30턴 후 이력의 크기입니다. 그 토큰 하나하나가 다음 요청에서 다시 입력으로 계산됩니다. 31번째 요청은 그 61,000 토큰 이력에 새 500 토큰 질문을 더하므로 입력이 61,500 토큰입니다. MiniMax-M2.7에서 1,500 토큰 답변이면 $0.0033입니다. 같은 요청에 대한 세 모델 전부이며, 비교를 위해 OpenRouter 가격도 함께입니다:

같은 채팅이 가장 작은 윈도를 약 100턴 만에 채웁니다:

(200,000 − 1,000) / 2,000 = 99.5

넘치면 제공자가 요청을 거부합니다. 상태 코드는 제공자마다 다르므로 오류 본문을 읽으세요. 예를 들어 Claude의 413 request_too_large는 바이트 단위 요청 크기(Messages의 경우 32 MB)에 관한 것으로, 토큰 윈도와는 다른 한도입니다.

할 일:

• 가장 오래된 턴을 버리거나 짧은 요약으로 대체하세요.
• 작업에 한 챕터만 필요할 때 문서 전체를 붙여넣지 마세요.
• 전체 텍스트가 정말 필요하면 윈도가 더 큰 모델로 옮기세요.

5. 답변이 잘림#

여기엔 오류가 없고, 그래서 이 경우가 혼란스럽습니다. 모델이 max_tokens나 모델 자체의 출력 한도에 도달해 그냥 멈춘 것입니다. Chat Completions 형식에서 표시는 choice의 finish_reason: "length"입니다.

CheapTokens에서 DeepSeek-V4-Flash는 답변당 최대 32,768 토큰을 반환할 수 있고, GLM-5.3-Flash와 MiniMax-M2.7은 최대 8,192입니다. max_tokens가 그보다 낮으면 올리세요. 이미 한도에 있다면 작업을 나누거나("3부 중 1부 작성") 모델에게 마지막 문장부터 이어 쓰라고 요청하세요.

MiniMax-M2.7 출력은 1M 토큰당 $0.15로 책정되며, 출력에서 OpenRouter보다 저렴합니다.

같은 문제, 다른 이름#

제공자들은 같은 원인에 다른 이름을 붙입니다. 2026년 10월 20일 기준 문서 내용입니다:

출처: DeepSeek error codes, Claude API errors. 두 페이지 모두 게시 날짜를 표시하지 않으므로 확인 날짜는 저희 기준입니다.

핵심: 문구로 추측하지 마세요. 오류는 type와 message를 담은 error 객체가 있는 JSON으로 돌아옵니다. 메시지 텍스트는 바뀌므로 상태와 타입으로 매칭하세요.

실제로 무엇이 돌아오는지 보기#

이 스니펫은 실패한 요청의 상태와 본문, 성공한 요청의 finish_reason를 출력합니다. 테스트 로그가 아니라 진단용 스케치입니다: 자신의 키로 실행하고 결과를 읽어보세요.

# Placeholders: YOUR_API_KEY, MODEL_ID (a model id you have access to)
from openai import OpenAI, APIStatusError

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.cheaptokens.dev/v1")

try:
    r = client.chat.completions.create(
        model="MODEL_ID",
        messages=[{"role": "user", "content": "Write a long checklist."}],
        max_tokens=1000,
    )
except APIStatusError as e:
    # Read the status and the body, not the wording of the message
    print("status:", e.status_code)
    print("body:", e.body)
else:
    print("finish_reason:", r.choices[0].finish_reason)  # "length" = cut off
    print("usage:", r.usage)  # prompt_tokens and completion_tokens

점검이 잔액을 가리킨다면#

잔액을 충전하고 요청을 다시 보내세요. CheapTokens의 가격은 모델별로 고정되어 있고, 피크 시간이 없으며, 하나의 잔액이 모든 모델을 커버하므로 모델마다 따로 충전할 필요가 없습니다. 현재 요금은 여기 있습니다:

충전하기 전에 자신의 사용량을 비용 표에 넣어보세요. 숫자가 맞으면 Top up your balance하고, 더 큰 작업량을 먼저 추정하고 싶다면 How to estimate the cost of an AI agent를 보세요.