エラーコードとトラブルシューティング

1折AI を呼び出す際に 401、404、429、529、5xx、タイムアウト、および Claude Code のエラーが発生した場合の原因と対処方法。

まず以下のチェックリストを順に確認してください。ほとんどの問題は最初の 3 ステップで特定できます。

トラブルシューティングの順序

アドレス：Anthropic 系ツールには https://1zheai.com、OpenAI 系には https://1zheai.com/v1 を入力します。詳細は Base URL と認証を参照してください。
API キー（API key）：完全か（余分なスペースや改行がないか）、削除されていないか、正しいフィールドに入力されているかを確認します。
残高：コンソールの残高が十分かを確認します。
モデル ID：サポートされているモデルと完全に一致しているかを確認します。
ネットワーク：プロキシをオフにして直接接続で再試行します。
それでも解決しない場合：最小限の curl で再現（下記参照）し、レスポンスと所要時間をお知らせください。

1
curl -i https://1zheai.com/v1/messages \
2
  -H "x-api-key: sk-你的Key" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

-i はステータスコードとレスポンスヘッダーを一緒に出力するため、トラブルシューティングに役立ちます。

エラーコード早見表

ステータスコード	よくある原因	対処方法
400	リクエストボディに問題：パラメータ名の誤り、フィールド型の誤り、`max_tokens` がモデルの上限を超える、上流が認識しない beta フィールドが含まれる	`message` が指摘するフィールドを確認；Claude Code の場合は下記「Extra inputs are not permitted」を参照
401	API キーが無効、削除済み、無効化済み、期限切れ、自身のクォータを使い切った、または未送信・リクエストヘッダーの配置ミス	レスポンスはすべて `Invalid token` なので、項目ごとに確認；Anthropic ネイティブの場合は `x-api-key` または `Authorization: Bearer`
403	アカウント残高不足（`billing_error` / `insufficient_quota`）；この API キーで当該モデルが有効になっていない；リクエスト元 IP がこの API キーのホワイトリストにない（いずれも `permission_error`）	課金するか、「API キー」ページでこの API キーのモデル制限と IP ホワイトリストを編集
404	パスが不正、またはモデルが存在しない／現在利用不可	`Invalid URL` でアドレスを確認；`not_found_error` / `model_not_found` でモデル ID と利用可能リストを確認
413	リクエストボディが大きすぎる	1 回に送信する内容を減らし、大きなファイルは分割
429	上流による一時的なレート制限。現時点で API キーに対するレート制限は設けていません	後で再試行；バッチ処理には指数バックオフを追加
503	モデルは存在するが、一時的に健全な上流サービスがない、またはサービスの一時的な障害	後で再試行；継続的に失敗する場合はリクエスト ID を添えてサポートに連絡
500 / 502	ゲートウェイまたは上流の一時的な障害	後で再試行；継続的に発生する場合は [email protected] にメール送信
504	リクエストがタイムアウト	長い出力にはストリーミングを使用；クライアントのタイムアウトを延長
529	上流 Anthropic の過負荷（`overloaded_error`）	数秒待って再試行、または一時的に別のモデルに切り替え

Anthropic 公式のエラータイプ（invalid_request_error、authentication_error、rate_limit_error、overloaded_error など）の完全な意味は公式 Errors ドキュメントを参照してください。

上流から返されたエラーは、ステータスコードと message をそのまま返し、message の末尾に今回のリクエストの request id を追加します。/v1/messages を使う場合は外側が公式の {"type":"error","error":{...}} 構造で、error.type はステータスコードに応じて公式の型が入ります。/v1/chat/completions を使う場合は OpenAI の {"error":{...}} 構造です。

実測レスポンス

以下は 2026-10-15 に /v1/messages に対して実測した実際のレスポンスです。/v1/chat/completions を使う場合は内容は同じで、外側に "type":"error" がなく、error に code フィールドが 1 つ追加されます。

{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}

{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}

{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}

{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}

{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}

{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}

モデルが存在しない／利用不可の場合の 404 の説明はサポートされているモデルを参照してください。レスポンス内の request id は今回のリクエストに対応するため、問題を報告する際は添付してください。

症状別トラブルシューティング

401 / Invalid token

API キーのコピー時にスペースや改行が含まれていた場合、再コピーしてください。
API キーがコンソールで削除または無効化された、期限切れ、または自身のクォータを使い切った場合。これらのいずれの場合もレスポンスは同じ Invalid token です。
Claude Code で ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN の両方が設定され、一方が古い値の場合：どちらか一方だけ残し、ANTHROPIC_AUTH_TOKEN を推奨します。
settings.json の env はターミナルで export した同名変数を上書きします。ターミナル変数の変更が反映されない場合は ~/.claude/settings.json を確認してください。

404 / Invalid URL

まずエラータイプを確認してください：not_found_error または model_not_found の場合はモデル ID と利用可能リストを確認します。Invalid URL の場合は /v1 を確認します：OpenAI SDK、Cursor、Cline（OpenAI Compatible）は https://1zheai.com/v1 に入力；Claude Code と Anthropic SDK は https://1zheai.com のみを入力し、/v1 を入力すると /v1/v1/messages になります。

403 / error code: 1010

レスポンスに error code: 1010 の行のみがあり JSON がない場合、リクエストはゲートウェイに到達する前にブロックされたことを意味します。現時点で Python 標準ライブラリの urllib で直接リクエストを送ると発生することが知られています（デフォルトの User-Agent は Python-urllib/3.x）。リクエストヘッダーに独自の User-Agent を追加するか、公式 SDK、requests、httpx に切り替えてください。

429 太多リクエスト

現時点で API キーに対するレート制限は設けていません。429 を受け取った場合、通常は上流の負荷が高いため、後で再試行してください。バッチ処理には指数バックオフを推奨します：失敗後、一定時間待ってから再試行し、待機時間を毎回倍増させ、並列数は自分でキューで制御してください。

529 / overloaded_error

上流 Anthropic が一時的に過負荷状態で、API キーや残高とは無関係です。数秒待って再試行してください。急ぎの場合は同一シリーズの別のモデルに一時的に切り替えてください。

タイムアウト、ストリーミングの途中切断

長い回答には可能な限りストリーミング（"stream": true）を使用してください。中間のネットワーク機器に切断されにくくなります。
Claude Code では API_TIMEOUT_MS でタイムアウトを延長できます。デフォルトは 600000（10 分）です。
プロキシを有効にしている場合は、一度プロキシをオフにして試してください。切断の多くはプロキシノードに起因します。

Claude Code：ログイン画面が直接表示される

Claude Code が API キーを読み取っていないことを意味します。Claude Code で /status を実行し、base URL と認証情報のソースの 2 行を確認してください。空の場合は Claude Code 接続に戻って環境変数または settings.json を確認してください。

Claude Code：Extra inputs are not permitted / context_management が 400 を返す

Claude Code はリクエストに実験的な beta フィールドを含めるため、厳格な上流が認識しないと 400 が返されます。以下の環境変数を設定して無効化してください（Claude Code 公式 LLM gateway ドキュメントより）：

1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

残高は十分なのに呼び出しに失敗する

特定のモデルのみ失敗する場合、そのモデルが一時的に利用不可、ID の入力誤り、またはこの API キーにモデル制限が設定されている可能性があります（403 This token has no access to model …）。
すべて失敗し 401 の場合、この API キーにクォータ上限が設定され使い切ったか、期限切れになっていないかを確認してください。「API キー」ページの「クォータ ($)」と「期限」の列で確認できます。
その他の場合は上記のエラーコード表を参照してください。

有限リトライとフィードバックテンプレート

無限ループで設定エラーを隠さないでください。SDK のタイムアウト、自動リトライ回数、バックオフの扱いはタイムアウトとリトライを参照してください。

サポートに連絡する際は以下のテンプレートをコピーし、キー、認証リクエストヘッダー、個人情報を削除してから送信してください：

1
发生时间与时区：
2
客户端及版本：
3
请求方法与完整路径：
4
模型 ID：
5
HTTP 状态码：
6
request id（如有）：
7
脱敏后的错误正文：
8
最小请求能否复现：
9
是否使用代理 / 是否仅某个模型失败：

それでも解決しない場合

[email protected] にメール送信し、日時、モデル ID、使用したツールとバージョン、curl -i の完全な出力（API キーは削除）を添付してください。