When something goes wrong with a workflow, Copelf returns structured error responses with machine-readable codes. This page covers every error code, its meaning, and how to resolve it.

Error Response Format#

All API errors follow a consistent JSON structure:

{
  "code": "workflow_not_found",
  "message": "The requested workflow does not exist.",
  "requestId": "req_abc123",
  "details": null
}

Authentication Errors#

unauthenticated#

Causes:

• Your session has expired.
• You are not signed in.
• The request was made without valid authentication headers.

Fixes:

1. Sign in again at copelf.com.
2. If using the browser extension, ensure it is connected to your Copelf account.
3. Clear your browser cookies and sign in fresh if the issue persists.

forbidden#

Causes:

• You are trying to access a workflow or resource owned by another user.
• Your account does not have the required role or plan.

Fixes:

1. Verify you are signed in with the correct account.
2. Check that you own or have been granted access to the resource.

Workflow Errors#

workflow_not_found#

Causes:

• The workflow was deleted.
• The workflow ID in the URL or API call is incorrect.

Fixes:

1. Double-check the workflow ID.
2. Open your Dashboard and confirm the workflow still appears in your list.

workflow_not_ready#

Causes:

• The uploaded video is still being analyzed by the AI.
• Analysis failed silently.

Fixes:

1. Wait for the analysis to complete -- this typically takes 1-3 minutes depending on video length.
2. If the status stays on "Analyzing" for more than 10 minutes, try re-uploading the video.

workflow_already_running#

Causes:

• You attempted to start a run while a previous run is still executing.

Fixes:

1. Wait for the current run to finish, or cancel it first.
2. Check the Runs tab to see the active run's status.

workflow_has_active_requests#

Causes:

• The workflow has pending approval requests or other active operations.

Fixes:

1. Navigate to the workflow's Runs tab and resolve any pending approval requests.
2. Wait for all active requests to complete before making changes.

Batch Errors#

batch_not_found#

Fixes:

1. Verify the batch ID is correct.
2. Check your Batches list to confirm it exists.

batch_already_completed#

Fixes:

• A completed batch cannot be restarted. Create a new batch if you need to run the same iterations again.

Credit & Billing Errors#

insufficient_credits#

Fixes:

1. Check your current credit balance on the Billing page.
2. Purchase additional credits or apply a coupon code.

checkout_failed#

Fixes:

1. Verify your payment method is valid and has sufficient funds.
2. Try a different payment method.
3. If the issue persists, contact support with your requestId.

no_stripe_customer#

Fixes:

1. Navigate to Settings > Billing and set up your billing profile.
2. This usually happens on first purchase -- completing the checkout flow will create the profile automatically.

price_not_found#

Fixes:

• The pricing plan you selected may have been retired. Refresh the pricing page and select a current plan.

Coupon Errors#

Common fixes for coupon errors#

1. Double-check the coupon code for typos.
2. Verify the coupon is still within its valid date range.
3. Each coupon can only be redeemed once per account -- if you see coupon_already_redeemed, the credits should already be in your balance.
4. If you believe there is an error, contact support with the coupon code and your requestId.

General Errors#

bad_request#

Check the details field for specifics. Common causes:

• Missing required fields in the request body.
• Invalid field types (e.g., sending a string where a number is expected).

unprocessable_entity#

The request structure is correct, but the values are not valid:

• A variable name that conflicts with a reserved keyword.
• An input value that fails validation rules.

timeout#

Fixes:

1. The operation took too long to complete. Retry after a short wait.
2. For long-running workflows, consider breaking them into smaller steps.

internal#

Fixes:

1. This is a server-side issue. Retry the operation after a few seconds.
2. If the error persists, contact support with the requestId.

Common Issues#

Next Steps#