エラーコードと対処

400、401、パス関連エラーに関する検証済みガイダンスに加え、403、429、タイムアウト系障害への実践的な対処法で、CometAPI のリクエスト失敗をトラブルシュートします。

CometAPI のエラー処理は、リクエストの問題、認証の問題、再試行可能なプラットフォーム問題を分けて考えると最も簡単になります。このページは CometAPI の正式なエラーガイドであり、まずクライアント側から確認できることに焦点を当てています。

このガイドは、現在の CometAPI API に対する実環境での確認に基づいています。400、401、およびパス/base URL の失敗は直接検証しました。413、429、500、503、504、524 については制限付きテストで再現していないため、これらのステータスに関するガイダンスは意図的に保守的になっています。

​

クイックトリアージ

Status	通常の意味	Retry?	最初の対応
400	リクエストが正常にルーティングされる前に、リクエストのバリデーションに失敗しました。	No	model、messages、JSON の構造、フィールドの型を検証してください。
401	API キーが存在しない、不正な形式である、または無効です。	No	Authorization: Bearer <COMETAPI_KEY> を確認してください。
403	アクセスがブロックされた、または現在のリクエストが許可されていませんでした。	通常は No	正常に動作することが分かっているリクエストで再試行し、まずモデル固有のフィールドを削除してください。
Path mistake	base URL または endpoint path が誤っています。Comet では、きれいな JSON 404 ではなく、301 リダイレクトや HTML として現れる場合があります。	No	https://api.cometapi.com/v1 を正確に使用し、デバッグ中はリダイレクトの自動追従を無効にしてください。
429	レート制限、または一時的な飽和状態です。	Yes	ジッター付きの指数バックオフを使用してください。
500, 503, 504, 524	プラットフォーム障害またはタイムアウト系の障害です。	Yes	バックオフ付きで再試行し、request id を保持してください。

​

エラーエンベロープ

CometAPI が返す現在の JSON エラーエンベロープは次のようになっています。

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

多くの実際のエラーメッセージには、error.message の中に request id も含まれています。サポートが必要な場合は、その値を保存してください。

​

400 Bad Request

model を省略したときに、実際の API で観測された内容は次のとおりです。

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

実際には、400 は通常、プラットフォームがモデルプロバイダーへルーティングする前に、リクエストボディのバリデーションに失敗したことを意味します。

よくある原因:

• model や messages などの必須フィールドが不足している
• JSON の構造が無効
• 誤った型のフィールドを送信している
• 選択した endpoint では受け付けないプロバイダー固有のパラメータを使い回している

対処方法:

1. 最小限の正常なリクエストから始めます。
2. オプションフィールドを 1 つずつ戻します。
3. API リファレンスの endpoint schema とリクエストボディを比較します。

最小限の正常な例:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

your-model-id は、CometAPI Models page にある現在の model ID に置き換えてください。

​

401 Invalid Token

無効なキーを使用した際に、実際の API で観測された内容は次のとおりです。

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

確認すること:

1. ヘッダーは必ず Authorization: Bearer <COMETAPI_KEY> と完全一致している必要があります。
2. アプリが .env、シェル履歴、またはデプロイ済みのシークレットストアから古いキーを読み込んでいないことを確認してください。
3. 同じリクエストで 1 つのキーは失敗し、別のキーは成功する場合は、endpoint の問題ではなく token の問題として扱ってください。

​

403 Forbidden

制約付きテストでは安定して 403 を再現できなかったため、古い単一のメッセージテンプレートだけを全体像として扱わないでください。

現在の Comet ドキュメントでは、403 は主に次のいずれかの状況として説明されています:

• WAF フィルタリングなど、プラットフォーム側のルールによってリクエストがブロックされている
• token または route に、要求された model やリクエスト形式を使用する権限がない
• 選択した model が、渡した高度なパラメータのいずれかを拒否している

最初に行うこと:

1. 問題ないことが分かっている model に対して、非常にシンプルなテキストリクエストで再試行します。
2. 高度なフィールドとプロバイダー固有のパラメータを削除し、その後徐々に戻していきます。
3. レスポンスに request id が含まれている場合は、サポートへ連絡する前に必ず控えておきます。

メッセージ内に group や channel のような内部用語が出てきた場合、それらはルーティングの詳細として扱い、クライアント側で最初に診断すべき対象とは考えないでください。実際の対処としては、まず token、model、リクエスト形式を確認することが重要です。

​

間違った Base URL または間違ったパス

これは、古いページの記述が最も正確ではなかった領域です。

現在の Comet エンドポイントに対する実際の確認では:

• https://api.cometapi.com/chat/completions への POST は、https://www.cometapi.com/chat/completions への 301 リダイレクトを返しました
• https://api.cometapi.com/v1/not-a-real-endpoint のような存在しない API route への POST も、https://www.cometapi.com/v1/not-a-real-endpoint への 301 リダイレクトを返しました

これは、パスの誤りが次のような形で現れる可能性があることを意味します:

• リダイレクト
• クライアントがリダイレクトを追跡した場合の非 JSON の HTML レスポンス
• SDK 内部でのパースエラー
• API レイヤーに正常に到達しないリクエスト

この Base URL を正確に使用してください:

https://api.cometapi.com/v1

推奨される確認項目:

1. Base URL に /v1 が含まれていることを確認します。
2. エンドポイントパスがドキュメントと完全に一致していることを確認します。
3. パスの問題をデバッグしている間は、自動リダイレクト追跡を無効にします。

​

413 Request Entity Too Large

制約付きテストでは、8 MiB の大きすぎる JSON リクエストボディでも 413 を再現できなかったため、古い説明の「prompt が長すぎる」という見方は限定的すぎました。

413 が発生した場合は、まず リクエストサイズ の問題として扱ってください。よくある原因は次のとおりです:

• 大きな base64 ペイロード
• インラインで埋め込まれた大きすぎる画像や音声
• 非常に大きな multipart または JSON ボディ

対処方法:

1. 添付コンテンツを削減または圧縮します。
2. 大きなジョブはより小さなリクエストに分割します。
3. 原因がプレーンテキストの長さだけだと決めつけないでください。

​

429 Too Many Requests

24 並列の GET /v1/models リクエストによる制約付き同時実行プローブでは 429 を再現できなかったため、正確なしきい値は route、model、現在のプラットフォーム状態に明らかに依存します。

429 は再試行可能として扱ってください:

1. ジッター付きの指数バックオフを使用します。
2. バースト時の同時実行数を減らします。
3. どの route と model が最初に飽和しているか確認できるよう、リクエストログを有効にしておきます。

再利用可能な再試行パターンについては、チャット補完 のバックオフ例を参照してください。

​

500, 503, 504, And 524

制約付きテストでは、これらのステータスは再現できませんでした。これらはユーザーのミスではなく、サーバー側またはタイムアウト系の障害 として記載すべきです。

実務的なガイダンス:

• 500: プラットフォーム内部またはプロバイダー側の障害
• 503: route またはプロバイダーサービスが一時的に利用不可
• 504 と 524: プラットフォーム、エッジ、またはプロバイダーサービス間で発生するタイムアウト系の障害

対処方法:

1. バックオフ付きで再試行します。
2. request id、エンドポイント、model、timestamp を記録します。
3. 同じ障害が複数回の再試行でも繰り返される場合は、その情報を添えてサポートに連絡してください。

​

サポートに問い合わせる前に

まず以下の詳細を収集してください：

• HTTP メソッド
• エンドポイントパス
• モデル名
• サニタイズ済みのリクエスト body JSON（ほとんどの API 呼び出しで、これが最も有用な情報です）
• 失敗したリクエストで使用した場合はクエリパラメータ
• クライアントが取得している場合は、正確なレスポンス body
• 完全な HTTP ステータス
• 正確な error.message
• request id があればそれ
• おおよそのタイムスタンプ
• 同じリクエストが別の model または別のトークンで動作するかどうか

失敗したルートが、プレーンな JSON body ではなく ファイルアップロード（画像編集、音声アップロード、動画生成など）を受け付ける場合は、同等の送信 payload を共有してください：

• ファイルと一緒に送信したフィールド名とテキスト値
• ファイル名、ファイルタイプ、おおよそのファイルサイズ
• ファイルを直接アップロードしたのか、URL で参照したのか、base64 として埋め込んだのか

バグを最も速く再現する方法は、正確なサニタイズ済みリクエスト payload を得ることです。ほとんどの API 呼び出しでは、これは 生のリクエスト body JSON を意味します。ファイルアップロードのルートでは、フィールド一覧とファイルのメタデータを意味します。

これにより、サポート対応までの時間を大幅に短縮できます。