--- title: "エラーコードとトラブルシューティング" description: "1折AI を呼び出す際に 401、404、429、529、5xx、タイムアウト、および Claude Code のエラーが発生した場合の原因と対処方法。" headingIds: {"トラブルシューティングの順序":"section-1","エラーコード早見表":"section-2","実測レスポンス":"section-3","症状別トラブルシューティング":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 太多リクエスト":"section-8","529 / overloaded_error":"section-9","タイムアウト、ストリーミングの途中切断":"section-10","Claude Code：ログイン画面が直接表示される":"section-11","Claude Code：Extra inputs are not permitted / context_management が 400 を返す":"section-12","残高は十分なのに呼び出しに失敗する":"section-13","有限リトライとフィードバックテンプレート":"section-14","それでも解決しない場合":"section-15"} --- まず以下のチェックリストを順に確認してください。ほとんどの問題は最初の 3 ステップで特定できます。 ## トラブルシューティングの順序 1. **アドレス**：Anthropic 系ツールには `https://1zheai.com`、OpenAI 系には `https://1zheai.com/v1` を入力します。詳細は [Base URL と認証](/ja/docs/base-url/) を参照してください。 2. **API キー（API key）**：完全か（余分なスペースや改行がないか）、削除されていないか、正しいフィールドに入力されているかを確認します。 3. **残高**：コンソールの残高が十分かを確認します。 4. **モデル ID**：[サポートされているモデル](/ja/docs/models/) と完全に一致しているかを確認します。 5. **ネットワーク**：プロキシをオフにして直接接続で再試行します。 6. **それでも解決しない場合**：最小限の curl で再現（下記参照）し、レスポンスと所要時間をお知らせください。 ```bash title="最小复现" curl -i https://1zheai.com/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -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 | ゲートウェイまたは上流の一時的な障害 | 後で再試行；継続的に発生する場合は support@1zheai.com にメール送信 | | 504 | リクエストがタイムアウト | 長い出力にはストリーミングを使用；クライアントのタイムアウトを延長 | | 529 | 上流 Anthropic の過負荷（`overloaded_error`） | 数秒待って再試行、または一時的に別のモデルに切り替え | Anthropic 公式のエラータイプ（`invalid_request_error`、`authentication_error`、`rate_limit_error`、`overloaded_error` など）の完全な意味は[公式 Errors ドキュメント](https://platform.claude.com/docs/en/api/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 つ追加されます。 ```json title="401 API 密钥无效、禁用、过期或额度用完" {"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"} ``` ```json title="403 账户余额不足" {"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"} ``` ```json title="403 API 密钥没开通该模型" {"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"} ``` ```json title="403 IP 不在白名单" {"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"} ``` ```json title="400 上游参数错误" {"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"} ``` ```json title="404 路径不存在" {"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}} ``` モデルが存在しない／利用不可の場合の 404 の説明は[サポートされているモデル](/ja/docs/models/) を参照してください。レスポンス内の 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 と利用可能リスト](/ja/docs/models/) を確認します。`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 接続](/ja/docs/quickstart-claude-code/) に戻って環境変数または `settings.json` を確認してください。 ### Claude Code：Extra inputs are not permitted / context_management が 400 を返す Claude Code はリクエストに実験的な beta フィールドを含めるため、厳格な上流が認識しないと 400 が返されます。以下の環境変数を設定して無効化してください（Claude Code 公式 LLM gateway ドキュメントより）： ```bash export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 ``` ### 残高は十分なのに呼び出しに失敗する - 特定のモデルのみ失敗する場合、そのモデルが一時的に利用不可、ID の入力誤り、またはこの API キーにモデル制限が設定されている可能性があります（403 `This token has no access to model …`）。 - すべて失敗し 401 の場合、この API キーにクォータ上限が設定され使い切ったか、期限切れになっていないかを確認してください。「API キー」ページの「クォータ ($)」と「期限」の列で確認できます。 - その他の場合は上記のエラーコード表を参照してください。 ## 有限リトライとフィードバックテンプレート 無限ループで設定エラーを隠さないでください。SDK のタイムアウト、自動リトライ回数、バックオフの扱いは[タイムアウトとリトライ](/ja/docs/retries/) を参照してください。 サポートに連絡する際は以下のテンプレートをコピーし、キー、認証リクエストヘッダー、個人情報を削除してから送信してください： ```text 发生时间与时区： 客户端及版本： 请求方法与完整路径： 模型 ID： HTTP 状态码： request id（如有）： 脱敏后的错误正文： 最小请求能否复现： 是否使用代理 / 是否仅某个模型失败： ``` ## それでも解決しない場合 support@1zheai.com にメール送信し、日時、モデル ID、使用したツールとバージョン、`curl -i` の完全な出力（API キーは削除）を添付してください。