エラーコードへの対処

​

クイックトリアージ

​

エラーエンベロープ

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

​

400 Bad Request

• model などの必須フィールドが欠けている
• JSON の形式が不正
• 誤った型でフィールドを送信している
• 選択したエンドポイントでは受け付けない provider 固有のパラメータを再利用している

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

​

500 Internal Server Error

{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}

1. リクエスト本文を修正します。
2. ペイロードをエンドポイントスキーマと比較します。
3. ペイロードを修正した後にのみリトライします。

​

401 Invalid Token

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

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

​

403 Forbidden

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

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

​

間違った base URL または間違った path

• リダイレクト
• クライアントがリダイレクトに従う場合の、JSON ではない HTML レスポンス
• SDK 内でのパースエラー
• API レイヤーに正常に到達しないリクエスト

https://api.cometapi.com/v1

1. base URL に /v1 が含まれていることを確認してください。
2. エンドポイント path がドキュメントと正確に一致していることを確認してください。
3. path の問題をデバッグしている間は、自動リダイレクト追従を無効にしてください。

​

413 Request Entity Too Large

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

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

​

429 Too Many Requests

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

​

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 または別のトークンで動作するかどうか

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