「トークンが足りない」エラー: 意味と修正方法

「トークンが足りない」は1つのエラーではありません。このフレーズは5つの異なる問題に使われます。残高が空、リクエストが速すぎる、キーが間違っている、プロンプトがモデルのコンテキストウィンドウに収まらない、または回答が出力上限に達して文の途中で止まった、です。それぞれに固有の対処法があり、それらを見分ける最速の方法はメッセージの文言ではなく、HTTPステータスとエラーボディです。

表で自分の症状を見つけ、チェックを実行し、対処法を適用してください。

「トークン」が意味しうる3つのこと#

エラーメッセージのこの単語は、3つの異なる量を指します。

• 残高。 トークンは支払い対象なので、「トークン切れ」は多くの場合「お金切れ」を意味します。プリペイドサービスではこれが残高です。
• 1分あたりの制限。 制限はリクエスト数または1分あたりのトークン数で数えられます。どちらかに達したら、対処は待って一度に送る量を減らすことです。
• ウィンドウサイズ。 コンテキストウィンドウは、モデルが1回のリクエストで読めるトークン数で、プロンプトとその回答を合わせたものです。

そして決して意味しないこと: APIキーはトークンの在庫ではありません。キーはアカウントを識別します。尽きるのはその背後の残高、またはキーに付随する制限です。単位自体が初めてなら、What is a token in AI? から始めてください。

1. 残高が空#

DeepSeekのAPIドキュメントはHTTP 402 Insufficient Balance を「残高を使い果たしました」と説明しています。ClaudeのAPIは請求と支払いの問題に402 billing_error を使います。名前は違っても状況は同じ: お金がなくなっています。

CheapTokensも原則は同じです: プリペイド残高、従量課金、すべてのモデルで1つの残高。なので何かが壊れたら、まず残高を見てください。10秒のチェックで、最もよくある原因を除外できます。

2. レート制限に達した#

DeepSeekはHTTP 429 Rate Limit Reached を、リクエストが速すぎる、または同時実行数やQPS制限を超えたと説明しています。対処はペースを整えること: 並列リクエストを減らし、エンドポイントを叩き続けるのではなく再試行の遅延を増やします (1秒、2秒、4秒)。

1つの罠。ClaudeのAPIは、ティアの月間支出上限に達したときにも429 rate_limit_error を返し、そのレスポンスには retry-after ヘッダーがありません。つまり待っても決して解消しない429は、速度ではなくお金の問題かもしれません。待っても改善しないなら、原因1に戻ってください。

3. キーが間違っている#

HTTP 401は両方のドキュメントでキーの問題です: DeepSeekはAPIキーの誤りとして挙げ、Claudeは authentication_error として挙げています。よくある理由は、キーと一緒にコピーされた余分なスペースや改行、削除または再生成されたキー、間違ったアドレスに送られたキーです。あるサービスのキーは別のサービスのURLでは動作しません。CheapTokensのベースURLは https://api.cheaptokens.dev/v1 です。

接続中に発生しうるその他のエラーについては、Common connection errors and how to fix them を参照してください。

4. プロンプトがコンテキストウィンドウに収まらない#

コンテキストウィンドウは、モデルが1回のリクエストで読むすべてを数えます: システムプロンプト、会話履歴全体、新しいメッセージ、そして回答のための余裕。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 かかります。同じリクエストを3つのモデルすべてで示し、比較のためにOpenRouterの価格も載せます:

同じチャットは約100ターンで最小のウィンドウを埋めます:

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

オーバーフローすると、プロバイダーはリクエストを拒否します。ステータスコードはプロバイダーによって異なるので、エラーボディを読んでください。たとえばClaudeの413 request_too_large はリクエストサイズ (バイト単位、Messagesでは32 MB) に関するもので、トークンウィンドウとは別の制限です。

対処法:

• 最も古いターンを削除するか、短い要約に置き換える。
• タスクが1章だけを必要とするなら、ドキュメント全体を貼り付けない。
• 全文が本当に必要な場合は、より大きなウィンドウのモデルに移る。

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の出力は100万トークンあたり $0.15 で、これは出力においてOpenRouterより安いです。

同じ問題、異なる名前#

プロバイダーは同じ原因に異なるラベルを付けます。2026年10月20日時点の各ドキュメントの記載は次のとおりです:

出典: DeepSeek error codes、Claude API errors。どちらのページにも公開日がないため、確認日は当方によるものです。

要点: 文言から推測しないでください。エラーはJSONで返り、error オブジェクトに type と message が入っています。メッセージ本文は変わるので、ステータスとtypeで照合してください。

実際に何が返るかを見る#

このスニペットは、失敗したリクエストのステータスとボディ、成功したリクエストの 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の価格はモデルごとに固定で、ピーク時間はなく、1つの残高がすべてのモデルをカバーするので、モデルごとに別々のチャージは不要です。現在の料金はこちらです:

チャージする前に、自分の利用量をコスト表に当てはめてください。数字が妥当なら残高をチャージし、より大きなワークロードを先に見積もりたい場合はHow to estimate the cost of an AI agentを参照してください。