メインコンテンツへスキップ

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 のエラー処理は、リクエスト形式の問題、認証の問題、パスの誤り、再試行可能なプラットフォーム障害 を切り分けると簡単になります。HTTP ステータス、error.code、error.message を組み合わせて、リクエストを修正すべきか再試行すべきかを判断してください。

​
クイックトリアージ

Status通常の意味Retry?最初の対応
400リクエストが通常どおり処理される前に、リクエストの検証に失敗しました。いいえmodel、messages、JSON の構造、フィールドの型を検証してください。
401API キーが欠落している、形式が不正、または無効です。いいえAuthorization: Bearer <COMETAPI_KEY> を確認してください。
403アクセスがブロックされたか、現在のリクエストが許可されていませんでした。通常はいいえ動作確認済みのリクエストで再試行し、まず model 固有のフィールドを削除してください。
Path mistakebase 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 の多くの失敗レスポンスでは、次のようなエラーボディが使われます。 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
一部のレスポンスでは code が空のままです。ステータスが 500 の場合は、error.code と error.message を判断の決め手として扱ってください。

​
400 Bad Request

400 は通常、リクエストが正常に処理される前に、リクエスト本文の検証に失敗したことを意味します。 よくある原因:
  • model などの必須フィールドが不足している
  • JSON の構造が不正
  • 誤った型でフィールドを送信している
  • 選択したエンドポイントで受け付けない provider 固有のパラメータを再利用している
まず最小限の動作確認済みリクエストから始め、その後でオプションフィールドを 1 つずつ戻してください。ペイロードを API リファレンスのエンドポイントスキーマと比較してください。 次のような最小限のリクエストを使ってください。 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
your-model-id は、CometAPI Models page にある現在の model ID に置き換えてください。 不正なチャットリクエストが常に 400 を返すとは限りません。messages などの必須チャットフィールドの欠落は、error.code: invalid_request を伴う 500 として現れる場合もあります。

​
500 Internal Server Error

ほとんどの 500 レスポンスは、プラットフォームまたはプロバイダーの障害を示します。Chat Completions では、一部の不正なリクエストが 500 として返されつつ、error.code: invalid_request を含むこともあります。 その一例が、messages を省略したリクエストです。 
{
	"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

トークンの失敗は通常、次のように見えます: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
確認すること:
  1. ヘッダーは正確に Authorization: Bearer <COMETAPI_KEY> である必要があります。
  2. アプリが .env、shell history、またはデプロイ済みのシークレットストアから古いキーを読み込んでいないことを確認してください。
  3. 同じリクエストで1つのキーは失敗し、別のキーは動作する場合は、endpoint の問題ではなくトークンの問題として扱ってください。

​
403 Forbidden

403 は、ほとんどの場合次のいずれかの状況です:
  • リクエストが、WAF フィルタリングなどのプラットフォーム側ルールによってブロックされている
  • token または route に、要求された model またはリクエスト形状を使用する権限がない
  • 選択した model が、渡した高度なパラメータのいずれかを拒否している
最初に行うこと:
  1. 動作確認済みの model に対して、非常にシンプルなテキストリクエストで再試行します。
  2. 高度なフィールドと provider 固有のパラメータを削除し、その後で段階的に戻します。
  3. レスポンスに request id が含まれている場合は、サポートに連絡する前にそれを控えておいてください。
メッセージに group や channel のような内部用語が含まれている場合、それらはルーティングの詳細として扱い、クライアント側で最初に診断すべきものとは考えないでください。実際の対処としては、まず token、model、リクエスト形状を検証することが重要です。

​
Wrong base URL or wrong path

Comet では、path の誤りは次のような形で表れることがあります:
  • リダイレクト
  • クライアントがリダイレクトに従う場合の非 JSON の HTML レスポンス
  • SDK 内部でのパースエラー
  • API レイヤーに正常に到達しないリクエスト
この base URL を正確に使用してください: 
https://api.cometapi.com/v1
推奨される確認項目:
  1. base URL に /v1 が含まれていることを確認します。
  2. endpoint 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 が最初に飽和しているかを確認できるよう、リクエストログを有効にしておきます。
再利用可能な再試行パターンについては、チャット補完 のバックオフ例を参照してください。

​
503, 504, and 524

これらのステータスは サーバー側またはタイムアウト系の障害 です。 実践的な指針:
  • 503: route または provider サービスが一時的に利用不可
  • 504 と 524: プラットフォーム、エッジ、または provider サービス間で発生するタイムアウト系の障害
対処方法:
  1. バックオフ付きで再試行します。
  2. request id、endpoint、model、timestamp を控えます。
  3. 同じ障害が複数回の再試行でも繰り返される場合は、その情報を添えてサポートに連絡してください。

​
サポートに連絡する前に

まず、次の詳細を記録してください。
  • HTTP メソッド
  • エンドポイントパス
  • model ID
  • サニタイズ済みのリクエスト body JSON（これはほとんどの API 呼び出しで最も有用な項目です）
  • 失敗したリクエストで使用していた場合はクエリパラメータ
  • クライアントが取得している場合は正確なレスポンス body
  • 完全な HTTP ステータス
  • 正確な error.message
  • 任意の request id
  • おおよそのタイムスタンプ
  • 同じリクエストが別の model または別のトークンで動作するかどうか
失敗したルートがプレーンな JSON body ではなく ファイルアップロード（画像編集、音声アップロード、動画生成など）を受け付ける場合は、同等の送信 payload を送ってください。
  • ファイルと一緒に送信したフィールド名とテキスト値
  • ファイル名、ファイルタイプ、おおよそのファイルサイズ
  • ファイルを直接アップロードしたのか、URL 参照なのか、base64 として埋め込んだのか
バグを再現する最も効果的な方法は、正確にサニタイズされたリクエスト payload です。ほとんどの API 呼び出しでは、これは 生のリクエスト body JSON を意味します。ファイルアップロードのルートでは、フィールド一覧とファイルのメタデータを意味します。
これにより、サポート対応の所要時間を大幅に短縮できます。