> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# エラーコードへの対処
> このガイドでは、CometAPI のエラーレスポンスを分類し、よくあるリクエスト失敗に対してリトライまたは修正手順を適用する方法を説明します。
CometAPI のエラー処理は、**リクエスト形式の問題**、**認証の問題**、**パスの誤り**、**リトライ可能なプラットフォーム障害**を分けて考えると簡単になります。HTTP status、`error.code`、`error.message` を組み合わせて、リクエストを修正すべきか、リトライすべきかを判断してください。
## クイックトリアージ
| Status | 通常の意味 | Retry? | 最初の対応 |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------- |
| `400` | リクエストが通常どおり処理される前に、リクエスト検証に失敗しました。 | いいえ | `model`、`messages`、JSON の形式、フィールドの型を検証します。 |
| `401` | API キーが存在しない、形式が正しくない、または無効です。 | いいえ | `Authorization: Bearer $COMETAPI_KEY` を確認します。 |
| `403` | アクセスがブロックされたか、現在のリクエストが許可されていませんでした。 | 通常はいいえ | 正常に動作することが分かっているリクエストで再試行し、まず model 固有のフィールドを削除します。 |
| Path mistake | ベース URL またはエンドポイントパスが誤っています。Comet では、これはきれいな JSON `404` ではなく、`301` リダイレクトや HTML として現れることがあります。 | いいえ | `https://api.cometapi.com/v1` を正確に使用し、デバッグ中はリダイレクトの自動追跡を無効にします。 |
| `429` | レート制限または一時的な飽和状態です。 | はい | ジッター付き指数バックオフを使用します。 |
| `500` with `error.code: invalid_request` | 不正な形式のリクエストが、サーバーステータスのレスポンスとして表面化したものです。 | いいえ | リトライする前にリクエスト本文を修正します。 |
| `500`, `503`, `504`, `524` | プラットフォーム、プロバイダー、またはタイムアウト系の障害です。 | はい | バックオフを使ってリトライし、request id を保持します。 |
## エラーエンベロープ
多くの CometAPI の失敗では、次のようなエラー本文が使われます。
```json theme={null}
{
"error": {
"message": "...",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
一部のレスポンスでは `code` が空のままになることがあります。status が `500` の場合は、判断の決め手として `error.code` と `error.message` を扱ってください。
## `400 Bad Request`
`400` は通常、リクエストが正常に処理される前に、リクエスト本文の検証に失敗したことを意味します。
よくある原因:
* `model` などの必須フィールドが欠けている
* JSON の形式が不正
* 誤った型でフィールドを送信している
* 選択したエンドポイントでは受け付けない provider 固有のパラメータを再利用している
最小限の正常動作するリクエストから始めて、オプションフィールドを 1 つずつ戻してください。ペイロードを API リファレンスのエンドポイントスキーマと比較します。
次のような最小限のリクエストを使用します。
```json theme={null}
{
"model": "your-model-id",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}
```
`your-model-id` は、[CometAPI Models page](/ja/overview/models) にある現在の model ID に置き換えてください。
不正な形式の chat リクエストが必ず `400` を返すとは限りません。`messages` のような必須の chat フィールドが欠けている場合でも、`error.code: invalid_request` を伴う `500` として表面化することがあります。
## `500 Internal Server Error`
ほとんどの `500` レスポンスは、プラットフォームまたはプロバイダーの障害を示します。Chat Completions では、一部の不正な形式のリクエストも、`error.code: invalid_request` を伴ったまま `500` として表面化することがあります。
その一例が、`messages` を省略したリクエストです。
```json theme={null}
{
"error": {
"message": "field messages is required (request id: ...)",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
`500` レスポンスに `error.code: invalid_request` がある場合は、リクエストの問題として扱ってください。
1. リクエスト本文を修正します。
2. ペイロードをエンドポイントスキーマと比較します。
3. ペイロードを修正した後にのみリトライします。
`500` レスポンスが無効なリクエストを示していない場合は、`request id` を保持してバックオフを使用してください。
## `401 Invalid Token`
トークンの失敗は通常、次のように見えます:
```json theme={null}
{
"error": {
"code": "",
"message": "invalid token (request id: ...)",
"type": "comet_api_error"
}
}
```
確認すること:
1. ヘッダーは必ず正確に `Authorization: Bearer $COMETAPI_KEY` である必要があります。
2. アプリが `.env`、シェル履歴、またはデプロイ済みのシークレットストアから古いキーを読み込んでいないことを確認してください。
3. あるキーでは失敗し、別のキーでは同じリクエストが成功する場合は、これをエンドポイントの問題ではなくトークンの問題として扱ってください。
## `403 Forbidden`
`403` は、ほとんどの場合次のいずれかの状況です:
* リクエストが WAF フィルタリングなどのプラットフォーム側ルールによってブロックされている
* トークンまたは route が、要求された model またはリクエスト形状の使用を許可されていない
* 選択した model が、渡した高度なパラメータのいずれかを拒否している
最初に行うこと:
1. 既知の正常な model に対して、非常にシンプルなテキストリクエストで再試行してください。
2. 高度なフィールドとプロバイダー固有のパラメータを削除し、その後で徐々に戻してください。
3. レスポンスに request id が含まれている場合は、サポートに連絡する前にそれを控えておいてください。
メッセージに `group` や `channel` のような内部用語が出てきた場合、それらはクライアント側で最初に診断すべき項目ではなく、ルーティングの詳細として扱ってください。実際の対処としては、引き続き token、model、リクエスト形状を先に検証することです。
## 間違った base URL または間違った path
Comet では、path の誤りは次のような形で現れることがあります:
* リダイレクト
* クライアントがリダイレクトに従う場合の、JSON ではない HTML レスポンス
* SDK 内でのパースエラー
* API レイヤーに正常に到達しないリクエスト
この base URL を正確に使用してください:
```text theme={null}
https://api.cometapi.com/v1
```
推奨される確認事項:
1. base URL に `/v1` が含まれていることを確認してください。
2. エンドポイント path がドキュメントと正確に一致していることを確認してください。
3. path の問題をデバッグしている間は、自動リダイレクト追従を無効にしてください。
## `413 Request Entity Too Large`
`413` が表示された場合、まず **リクエストサイズ** の問題として扱ってください。よくある原因は次のとおりです:
* 大きな base64 ペイロード
* インラインで埋め込まれた大きすぎる画像または音声
* 非常に大きな multipart または JSON ボディ
対処方法:
1. 添付コンテンツを縮小または圧縮してください。
2. 大きなジョブはより小さなリクエストに分割してください。
3. 原因がプレーンテキストの長さだけだとは決めつけないでください。
## `429 Too Many Requests`
`429` は再試行可能として扱ってください:
1. ジッター付きの指数バックオフを使用してください。
2. バースト時の同時実行数を減らしてください。
3. どの route と model が最初に飽和しているか確認できるよう、リクエストログを有効のままにしてください。
再利用可能な再試行パターンについては、[チャット補完](/api/text/chat) のバックオフ例を参照してください。
## `503`, `504`, and `524`
これらのステータスは **サーバー側またはタイムアウト系の失敗** です。
実践的なガイダンス:
* `503`: route またはプロバイダーサービスが一時的に利用不可
* `504` と `524`: プラットフォーム、エッジ、またはプロバイダーサービス間でのタイムアウト系の失敗
対処方法:
1. バックオフ付きで再試行してください。
2. `request id`、エンドポイント、model、タイムスタンプを記録してください。
3. 同じ失敗が複数回の再試行でも繰り返される場合は、その文脈情報を添えてサポートに連絡してください。
## サポートに問い合わせる前に
まず、以下の詳細を記録してください。
* HTTP メソッド
* エンドポイントのパス
* model ID
* **サニタイズ済みのリクエスト body JSON**（これはほとんどの API 呼び出しで最も有用な項目です）
* 失敗したリクエストで使用した場合はクエリパラメータ
* クライアントが取得している場合は正確なレスポンス body
* 完全な HTTP ステータス
* 正確な `error.message`
* `request id` があればその値
* おおよそのタイムスタンプ
* 同じリクエストが別の model または別のトークンで動作するかどうか
失敗したルートがプレーンな JSON body ではなく **ファイルアップロード**（画像編集、音声アップロード、動画生成など）を受け付ける場合は、送信したペイロードに相当する内容を送ってください。
* ファイルと一緒に送信したフィールド名とテキスト値
* ファイル名、ファイルタイプ、おおよそのファイルサイズ
* ファイルを直接アップロードしたのか、URL で参照したのか、base64 として埋め込んだのか
バグを再現する最も効果的な方法は、正確なサニタイズ済みリクエストペイロードです。ほとんどの API 呼び出しでは、これは **生のリクエスト body JSON** を意味します。ファイルアップロードのルートでは、フィールド一覧とファイルのメタデータを意味します。
これにより、サポート対応までの時間を大幅に短縮できます。