ブログに戻る

トラブルシューティングガイド

よくある接続エラーとその修正方法

CheapTokens APIに接続する際の401、402、400、404、413、429、503の意味、レスポンスの見え方、そしてそれぞれの修正方法。

投稿者: CheapTokens Team公開日 読了時間 4 分

HTTPステータスコード401、402、400、404、429の一覧と短い説明を表示したターミナル
このページの内容
  1. クイックチェック
  2. 401 — 無効なAPIキー
  3. 402 — 残高が空、またはリクエストにキーがない
  4. 404 — アドレスが間違っている
  5. 400 — モデルが見つからない
  6. 413 — リクエストが大きすぎる
  7. 429 — リクエストが多すぎる
  8. 503 — モデルが一時的に利用できない
  9. 長い待ち時間とタイムアウト

ほぼすべての接続問題は4つの原因に帰着します。アドレス、キー、モデルID、そして残高です。まず下記のクイックチェックを実行し、次に該当するステータスコードを確認してください。ここに引用しているレスポンスボディは、APIの実際のレスポンスです（2026年10月）。

クイックチェック#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

最初のコマンドが失敗する場合、原因はあなた側のネットワーク、アドレスのタイポ、あるいはサービス自体が一時的に利用できないことかもしれません。2つ目だけが失敗する場合は、下記のステータスコードを確認してください。両方とも成功するのにツールが動かない場合は、ツールの設定をこの2つのコマンドと比較してください。

401 — 無効なAPIキー#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Anthropicスタイルのクライアントでは、同じエラーが独自の形式で返ります。

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

原因:

  • キーのコピー時に文字が欠けている、スペースや引用符が入っている。
  • ダッシュボードでキーがローテーションされ、古いキーが使えなくなっている。
  • CheapTokensのキーではなく、別のサービス（たとえばOpenAI）のキーが設定されている。
  • このターミナルで環境変数が空になっている: echo ${#CHEAPTOKENS_API_KEY} で長さを表示できます。

ダッシュボードにキーが表示されるのは一度だけです。紛失した場合は Rotate を押して新しいキーを取得し、使用しているすべての場所で更新してください。

402 — 残高が空、またはリクエストにキーがない#

APIは2つの異なる状況で402を返します。

  1. 残高を使い切った。 リクエストは残高から支払われ、残高がなくなるとキーは一時停止されます。ダッシュボードでチャージすると、リクエストが再び通るようになります。
  2. リクエストにキーがまったくない。 Authorization ヘッダー（Anthropicスタイルのクライアントでは x-api-key）がない場合、APIはタイプ insufficient_funds の402を返します。ツールが本当にキーを送信しているか確認してください。OpenAIスタイルでは Authorization: Bearer <key> です。

404 — アドレスが間違っている#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

パスにタイポがあります — ここでは completions ではなく completion になっています。その他のよくある原因:

  • ベースURLに /v1 がない。 OpenAIスタイルのクライアントには https://api.cheaptokens.dev/v1 が必要です。/v1 がないとリクエストがAPIに届かず、JSONではなくプレーンなHTMLの404ページが返ります。
  • /v1 が二重になっている。 一部のクライアントは /v1 を自分で追加します。その場合、ベースURLはルート、つまり https://api.cheaptokens.dev でなければなりません。Anthropicスタイルのクライアントは常にルートアドレスを使用します。

400 — モデルが見つからない#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

モデルIDは、スラッシュより前のプレフィックスを含む完全なIDでなければなりません: deepseek-v4-flash ではなく deepseek-ai/DeepSeek-V4-Flash-0731 です。大文字と小文字は区別されません。エラーメッセージには利用可能なIDが一覧表示され、完全なリストは常に GET /v1/models にあります。

400は、不正な形式のリクエストボディに対しても返ります — たとえば空の messages 配列（messages field is required and must be a non-empty array）や、role のないメッセージです。

413 — リクエストが大きすぎる#

リクエストボディは16 MBに制限されています。エージェントは巨大なファイルやログをコンテキストに入れることでこの制限に達することがあります。モデルが必要とする部分だけを送信し、長いツール出力は切り詰めてください。

429 — リクエストが多すぎる#

429を受け取った場合は、ペースを落としてください。レスポンスには、待機すべき秒数を含む Retry-After ヘッダーが含まれます。公式のOpenAI SDKは自動的にリトライします（max_retries）。独自のコードでは、次の試行の前に Retry-After 待ってください。

503 — モデルが一時的に利用できない#

モデルが一時的に利用できないことがあり、その場合APIはタイプ model_unavailable の503を返し、サイト上のモデルカードには「一時的に利用不可」と表示されます。後でリトライするか、model フィールドを別のモデルに切り替えてください — キーとアドレスはそのままです。

長い待ち時間とタイムアウト#

zai-org/GLM-5.3-Flash のような推論モデルは回答する前に考えるため、最初のトークンに時間がかかることがあります。ストリーミング を使うか、クライアントのタイムアウトを延ばしてください — たとえばOpenAI SDKでは timeout=120 です。

タグ: