トラブルシューティング

エラーレスポンスの形式

Copelf のすべてのエラーは統一された JSON 構造で返されます。

{
  "error": {
    "code": "workflow_not_found",
    "message": "The requested workflow does not exist.",
    "status": 404
  }
}

エラー処理では code フィールドを使って分岐してください。message は変更される可能性があります。

コード	HTTP	原因	解決方法
`unauthenticated`	401	リクエストに有効な認証情報がない	ログインし直すか、セッションが切れていないか確認する
`forbidden`	403	認証済みだが操作権限がない	自分のアカウントが対象リソースのオーナーか確認する

401 が頻繁に出る場合は、ブラウザ拡張の接続状態を確認してください。拡張がログアウト状態だとすべてのリクエストが失敗します。

コード	HTTP	原因	解決方法
`workflow_not_found`	404	指定されたワークフローが存在しない	ワークフロー ID が正しいか確認する
`workflow_not_ready`	422	ワークフローの動画解析がまだ完了していない	解析完了を待ってから実行する
`workflow_already_running`	409	ワークフローがすでに実行中	現在の実行が完了するのを待つか、キャンセルしてから再実行する
`workflow_has_active_requests`	409	ワークフローに未処理のリクエストがある	アクティブなリクエストを完了またはキャンセルしてから操作する

workflow_not_ready は、動画をアップロードした直後に実行しようとすると発生します。動画解析が完了するとワークフローエディタが利用可能になります。

コード	HTTP	原因	解決方法
`batch_not_found`	404	指定されたバッチが存在しない	バッチ ID が正しいか確認する
`batch_already_completed`	409	バッチはすでに完了している	新しいバッチを作成して再実行する

コード	HTTP	原因	解決方法
`insufficient_credits`	402	クレジット残高が不足している	追加クレジットを購入するか、Plus プランにアップグレードする
`checkout_failed`	500	決済処理に失敗した	支払い方法を確認して再試行する
`no_stripe_customer`	404	Stripe 顧客情報がまだ作成されていない	設定ページから請求情報を登録する
`price_not_found`	404	指定された料金プランが存在しない	利用可能なプランを確認する

insufficient_credits が出た場合、実行中のワークフローは開始されません。事前にダッシュボードでクレジット残高を確認してください。

コード	HTTP	原因	解決方法
`coupon_not_found`	404	クーポンコードが見つからない	コードの入力ミスがないか確認する
`coupon_inactive`	422	クーポンが無効化されている	有効なクーポンを使用する
`coupon_expired`	422	クーポンの有効期限が切れている	新しいクーポンコードを取得する
`coupon_max_redemptions_reached`	422	クーポンの利用回数上限に達した	別のクーポンを使用する
`coupon_already_redeemed`	409	同じクーポンをすでに利用済み	1 つのクーポンは 1 アカウントにつき 1 回のみ利用可能

コード	HTTP	原因	解決方法
`bad_request`	400	リクエストの形式が不正	パラメータと型を確認する
`unprocessable_entity`	422	形式は正しいが内容が処理不能	入力値のバリデーションエラーを確認する
`not_found`	404	指定されたリソースが見つからない	URL やリソース ID が正しいか確認する
`conflict`	409	リソースの状態が競合している	現在の状態を確認してから操作をやり直す
`timeout`	408	処理がタイムアウトした	時間をおいて再試行する
`internal`	500	サーバー内部エラー	時間をおいて再試行し、解決しなければサポートへ連絡する

ワークフローが途中で止まる — ステップの target.description や vision.hint が曖昧だと、AI が正しい要素を見つけられず失敗することがあります。ワークフローエディタで説明文をより具体的にしてください。

バッチ実行が最初の数件で失敗する — 入力テーブルの値に空欄や型の不一致がないか確認してください。1 行目が失敗してもバッチは続行されますが、同じ原因が繰り返される場合は入力データを見直すほうが効率的です。

拡張機能が接続できない — ブラウザ拡張のアイコンをクリックして接続状態を確認してください。ブラウザの再起動やログインし直しで解決することがほとんどです。

ステップの検証が失敗する — ページの読み込みが遅い場合、AI が操作前後の差分を正しく認識できないことがあります。navigate ステップの waitUntil を networkidle に設定すると改善する場合があります。