One Click Videos · Developers

Errors and recovery

Use the error code and structured details to decide what to fix or retry.

HTTP error reference

HTTP Code Recovery
401 invalid_api_key Check the Bearer header and use a valid, unrevoked key.
402 subscription_required Restore an active paid subscription; inspect reason.
400 invalid_json Send a JSON object with Content-Type: application/json.
400 video_idea_required Add a creative idea. A URL alone is insufficient.
400 invalid_style_reference Send preset_style or my_style, not both.
400 style_not_available Choose an available published style.
400 insufficient_credits Check available and required; add credits or adjust the request.
400 engine_rejected Revise the brief. The rejected generation reserve is refunded.
404 style_not_found Use an ID from the correct styles list.
404 not_found Check the job ID and the key owner.
422 classic_fields_unsupported Remove the named classic fields; follow fields and hint.
422 brief_invalid Fix errors and problems entries before retrying.
422 reference_unreachable Use reachable public HTTPS image/audio assets within size limits.
422 content_blocked Revise the request to comply with the content policy.
422 wrong_page_type Provide the product or vehicle page required by the selected style.
500 config / style_hydration_failed / auth_mint_failed Service error. Reconcile recent jobs before retrying creation; contact support if repeated.
502 trigger_failed Queueing failed; the reserve is refunded. Check the job/account state before a new request.
503 v2_not_configured The director is temporarily unavailable. Try later.

Validation details

A brief_invalid response can contain errors and problems entries with code, field and say. Display the actionable message and correct the affected field. Repeating the same invalid body is unlikely to help.

A job can fail after creation succeeds

A successful create response only means that a job was accepted. The status endpoint can later return status: failed and an error object. Store that final error alongside the job ID.

Ambiguous failures

If the connection closes before a create response arrives, the server may still have accepted the video. Inspect recent jobs before resubmitting. Include the job ID, approximate time and error code when contacting support; exclude the API key.

Status and result fields →

Legacy request error example

{
  "error": "classic_fields_unsupported",
  "message": "This request carries classic fields the director API does not accept.",
  "fields": [
    "visualinstructions_1",
    "video_mode"
  ],
  "hint": "Describe the video in video_idea, optionally segments[].idea and notes. See https://jemsu.ai/docs/create-video/",
  "warnings": [
    "mapped videolength \u2192 video_length_sec"
  ]
}

Missing video idea

{
  "error": "video_idea_required",
  "message": "video_idea is required \u2014 a URL alone no longer describes a video.",
  "hint": "Say what happens, who or what is shown, the message and the tone."
}

Media and script validation

422 reference_unreachable means an image, logo or cloned-voice sample could not be fetched. Use public HTTPS media, the appropriate image/audio type and files no larger than 10 MB. This check happens before credits are charged.

For 422 brief_invalid, read errors and problems entries. If a dictated script is too long, shorten it, increase video_length_sec within its limit, or use planner to have the director write to the duration.