> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# モデル API エラーをトラブルシューティングするには？

> パラメータ、認証、429、5xx、タイムアウト、リソース、グループのエラーを診断します。

## 簡潔な回答

HTTPステータスコードだけでリクエストを診断しないでください。まず完全なエラー、モデル名、ベースURL、tokenグループ、リクエストIDを保存し、その後、問題が**リクエスト設定エラー**なのか、**一時的な上流障害**なのかを判断してください。

* `400`、`401`、`403`、未サポートのパラメーター、安全性ブロック、グループの不一致には、通常、リクエストまたは設定の変更が必要です。同じリクエストを繰り返しても解決しません。
* `429`、`503`、一部の`504`レスポンス、`Upstream model timed out`は、上流の負荷、リソースの可用性、または長時間実行されるリクエストが原因で発生する場合があります。ログを確認してから、制限付きの指数バックオフリトライを使用してください。
* 1つのモデルまたはグループだけが失敗する場合は、認証済みのフォールバックグループをテストしてください。複数のモデルが同時に失敗する場合は、まずAPIキー、ベースURL、ネットワーク経路を確認してください。

## 完全なエラーを保存する

スクリーンショットでは、最も有用なフィールドが省略されることがよくあります。トラブルシューティングの前に、次の情報を保存してください。

| 情報           | 例                             | 重要な理由                   |
| ------------ | ----------------------------- | ----------------------- |
| HTTPステータス    | `400`, `401`, `429`, `503`    | エラーの種類を特定できます           |
| エラーメッセージとコード | `Unsupported parameter: stop` | 決定論的なリクエストエラーを特定できます    |
| モデルとグループ     | `gpt-5.6-luna`, `Default`     | 影響を受けるルートを定義します         |
| ベース URL      | `https://api.apiyi.com/v1`    | エンドポイントとノード設定の確認に役立ちます  |
| リクエスト ID     | レスポンスで返される ID                 | サポートがリクエストを特定するのに役立ちます  |
| タイムスタンプ      | タイムゾーンを含めてください                | 上流システムおよびログ記録との照合に役立ちます |
| ログ記録         | 課金記録が存在するかどうか                 | 生成が開始されたかどうかを示します       |

<Warning>
  チケット、スクリーンショット、またはコードサンプルに完全な APIキーを記載しないでください。エラーメッセージ、リクエスト ID、および秘匿化した設定のみを残してください。
</Warning>

## エラーの種類別トラブルシューティング

| エラー                                            | 一般的な原因                                                       | 最初の対応                                                      |
| ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
| `400` または `Unsupported parameter`              | 一部の軽量モデルでの `stop` など、モデルがリクエストフィールドをサポートしていない                | サポートされていないフィールドを削除して最小限のリクエストをテストします。同じ内容のまま再試行しないでください    |
| `401 Invalid token` または `403`                  | APIキー、ベースURL、tokenの状態、またはグループ権限の不一致                          | APIキーとベースURLを確認し、続いてtokenのグループとモデル権限を確認します                 |
| `429`                                          | 過剰な同時実行数または上流の飽和です。メッセージにリクエスト互換性の問題が隠れている場合もあります            | 完全なエラーを確認し、同時実行数を減らして指数バックオフを使用します。解決しない場合はクォータとグループを確認します |
| `503` または `Service unavailable`                | 一時的な利用不能、上流リソースの不足、またはグループ内に利用可能なチャネルがない                     | 少し待ってから回数を制限して再試行します。必要に応じて、認証済みのフォールバックグループを使用します         |
| `504` または `Upstream model timed out`           | 上流での処理が長い、上流が不安定、またはリクエスト経路上のどこかでタイムアウトが発生している               | ログとクライアントのタイムアウトを確認します。長時間のリクエストにCDNノードを使用していないことを確認してください |
| `RESOURCE_EXHAUSTED`                           | 上流のコンピューティングリソースまたは同時実行数リソースが一時的に不足している                      | 同時実行数を減らして復旧を待つか、別の利用可能なグループまたはモデルを使用します                   |
| `rejected by the safety system` または `NO_IMAGE` | リクエストが上流のコンテンツ安全ポリシーに抵触した                                    | promptまたは入力を変更します。同じリクエストを変更せずに送信しないでください                  |
| モデルが利用できない、またはグループが不一致                         | tokenに必要なグループが含まれていない、モデルのホワイトリストによってブロックされている、またはモデル名が正しくない | tokenのプライマリグループ、フォールバックグループ、許可されているモデルを確認します               |

<Info>
  同じステータスコードでも、原因が異なる場合があります。たとえば、`429` は上流の飽和を意味する場合がありますが、完全なエラーメッセージにのみ詳細が表示されるリクエスト互換性の問題である可能性もあります。最終的な根拠として、レスポンスボディと呼び出しログを使用してください。
</Info>

## 標準的なトラブルシューティング手順

<Steps>
  <Step title="手順1：最小限のリクエストで再現する">
    オプションパラメータ、ツール定義、複雑な画像入力、長い prompt を一時的に削除します。モデル、必須メッセージ、認証情報だけを残します。これにより、リクエストエラーとルートまたはモデルのエラーを切り分けられます。
  </Step>

  <Step title="手順2：エンドポイント、token、グループを確認する">
    API キーが `api.apiyi.com` ベースURL とともに使用されていることを確認します。コンソールで、token のプライマリグループ、フォールバックグループ、使用可能なモデルを確認します。一部のモデルでは専用グループが必要です。
  </Step>

  <Step title="手順3：リトライが適切かどうかを判断する">
    `429`、`503`、および一時的なアップストリーム障害が確認された場合は、バックオフ付きリトライを使用します。パラメータエラー、安全性ブロック、無効なモデル名、グループの不一致の場合は、変更していないリクエストをリトライするのではなく、リクエストまたは設定を変更します。
  </Step>

  <Step title="手順4：タイムアウトとネットワーク経路を確認する">
    画像生成、推論モデル、長いテキストリクエストには、より長いタイムアウトが必要です。約100秒の制限がある `api-cf.apiyi.com` CDN ノードではなく、長いリクエストには `api.apiyi.com` または `vip.apiyi.com` を使用します。
  </Step>

  <Step title="手順5：再送信する前に呼び出しログを確認する">
    リクエストによって課金レコードが作成されたかどうかを確認します。クライアント側のタイムアウトや切断は、サーバー側の処理が停止したことを必ずしも意味しません。ステータスを確認する前に、リクエストを無条件に再送信することは避けてください。
  </Step>
</Steps>

## 最小テストリクエスト

次のリクエストを使用して、エンドポイント、token、基本的なモデル呼び出しを確認します。`YOUR_MODEL`を、お使いのtokenで利用可能なモデルに置き換え、最小限の呼び出しが機能するまでオプションフィールドを追加しないでください。

```bash theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {"role": "user", "content": "Reply with: test successful"}
    ]
  }'
```

## 繰り返し発生するエラーを防ぐ

* 最小限のリクエストから始め、`stop`、tools、推論制御、画像、その他のオプションフィールドを一度に1つずつ追加します。
* すべてのモデルが同じフィールドをサポートすると想定せず、モデルごとのパラメータ互換性テーブルを管理します。
* `429`の後に、多数の同時実行リクエストをすぐに再送しないでください。指数バックオフを使用し、モデルごとに同時実行数を制御します。
* 画像および推論のリクエストには、十分なタイムアウトを設定します。SDKのリトライと独自のビジネスレイヤーのリトライを重ねないでください。
* 実際の本番パラメータでテスト済みのフォールバックグループを設定します。

## よくある質問

<AccordionGroup>
  <Accordion title="429 は常に同時実行数が多すぎることを意味しますか？">
    いいえ。`429` は同時実行数または上流サービスの飽和が原因で発生する可能性がありますが、エラーメッセージにパラメータ互換性の問題が隠れている場合もあります。同時実行数を下げるかリクエストを変更するかを判断する前に、完全な `error.message` を確認してください。
  </Accordion>

  <Accordion title="401 の後は常に新しい token を作成する必要がありますか？">
    いいえ。まず、リクエストで APIYI のベース URL が使用されていることを確認し、次に token の有効期限が切れていないか、正しいグループが選択されているかを確認してください。1 つのモデルだけが 5xx またはタイムアウトエラーとともに `Invalid token` を返す場合は、上流ルートが原因である可能性もあります。
  </Accordion>

  <Accordion title="タイムアウトの直後にリトライできますか？">
    まず呼び出しログを確認してください。クライアントのタイムアウトは、クライアントが待機を停止したことを意味するだけであり、サーバー側の処理は継続している可能性があります。リクエストに課金記録がある場合、すぐにリトライすると重複した呼び出しが発生する可能性があります。
  </Accordion>

  <Accordion title="失敗したリクエストにも課金されますか？">
    エラーページだけを根拠に判断しないでください。モデル生成に到達しないパラメータ検証、認証、安全性によるブロックでは、通常、最終的な課金は発生しません。ただし、クライアントの切断や、上流サービスでの処理がすでに開始されたリクエストには、課金される可能性があります。正確な情報源として呼び出しログを使用してください。
  </Accordion>
</AccordionGroup>

## まだ解決しませんか？サポートにお問い合わせください

上記の手順を実行しても問題が解決しない場合は、WeComまたはメールでAPIYIサポートにお問い合わせください。トラブルシューティングを迅速に進めるため、以下の情報を含めてください。

* モデル名、tokenグループ、ベース URL
* 完全なエラーメッセージ、HTTPステータス、リクエストID
* 発生日時（`UTC+8`のタイムゾーンを含む）
* 最小化したリクエスト例、または機密情報を伏せたリクエストボディ
* 呼び出しログに課金記録が含まれているかどうか

<Warning>
  完全なAPIキーは絶対に送信しないでください。先頭部分と末尾の数文字だけを表示し、残りは伏せてください。
</Warning>

<CardGroup cols={2}>
  <Card title="WeComサポート" icon="message-circle" href="https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec">
    <img src="https://mintcdn.com/apiyillc/fpi567ydpk7adDt0/images/wecom-qrcode.png?fit=max&auto=format&n=fpi567ydpk7adDt0&q=85&s=7286b96e94110e3a48798b649df1b45b" alt="WeComサポートのQRコード" style={{maxWidth: "180px"}} width="400" height="400" data-path="images/wecom-qrcode.png" />

    QRコードをスキャンするか、このカードをクリックしてサポートに直接お問い合わせください。

    モデルエラー、タイムアウト、グループ、課金に関する問題
  </Card>

  <Card title="メールサポート" icon="mail">
    **サポート**: [support@apiyi.com](mailto:support@apiyi.com)

    件名には「モデルエラー」とモデル名を含めることをおすすめします。
  </Card>
</CardGroup>

## 関連ドキュメント

<CardGroup cols={2}>
  <Card title="APIキーが無効なのはなぜですか？" icon="key" href="/ja/faq/invalid-api-key">
    ベースURL、APIキー、認証設定を確認します
  </Card>

  <Card title="グループとは何ですか？" icon="layers" href="/ja/faq/groups-explained">
    tokenグループ、アップストリームルート、フォールバックグループについて説明します
  </Card>

  <Card title="リクエストのタイムアウトを回避するにはどうすればよいですか？" icon="timer" href="/ja/faq/timeout-configuration">
    タイムアウト、ノード、長時間リクエストのトラブルシューティングを設定します
  </Card>

  <Card title="どの程度の同時実行数を利用できますか？" icon="gauge" href="/ja/faq/api-concurrency">
    モデルの同時実行数制限と429に関する案内を確認します
  </Card>

  <Card title="サイトまたはAPIが502を返した場合はどうすればよいですか？" icon="server-crash" href="/ja/faq/website-502-error">
    5xxエラー、再試行、課金の確認について説明します
  </Card>

  <Card title="ログの課金額はどのように読み取ればよいですか？" icon="file-text" href="/ja/faq/log-billing-explained">
    呼び出しログを使用して、リクエストに課金されたかどうかを確認します
  </Card>
</CardGroup>