Skip to main content
All Clipzy API errors follow this structure: 
{
  "success": false,
  "message": "Human-readable description of the error",
  "error": {
    "detail": "Technical detail about the failure",
    "code": "ERROR_CODE"
  }
}
Use the error.code field to identify the error programmatically and handle it in your integration.

​
File upload errors

Error code: UNSUPPORTED_FORMAT
{
  "success": false,
  "message": "The uploaded file format is not supported.",
  "error": {
    "detail": "Received file with extension .flv. Supported formats: mp4, mov, avi, mkv, webm.",
    "code": "UNSUPPORTED_FORMAT"
  }
}
Clipzy accepts mp4, mov, avi, mkv, and webm files. Convert your video to one of these formats before uploading. For example, using ffmpeg:
ffmpeg -i input.flv -c:v libx264 -c:a aac output.mp4
Error code: FILE_TOO_LARGE
{
  "success": false,
  "message": "Uploaded file exceeds the maximum allowed size.",
  "error": {
    "detail": "File size is 2341 MB. Maximum allowed is 1000 MB.",
    "code": "FILE_TOO_LARGE"
  }
}
The upload was rejected because it exceeded the MAX_FILE_SIZE_MB limit configured on the server. You have two options:
  1. Ask your administrator to increase MAX_FILE_SIZE_MB.
  2. Trim or compress the video before uploading. See the performance guide for tips on reducing file size.

​
Job errors

Error code: VIDEO_NOT_FOUND
{
  "success": false,
  "message": "The specified video could not be found.",
  "error": {
    "detail": "No video with id 'vid_xyz999' exists.",
    "code": "VIDEO_NOT_FOUND"
  }
}
The video_id you provided does not match any uploaded video. Check for typos in the ID. If you are sure the video was uploaded, it may have been deleted or may be stored on a different deployment.
Error code: JOB_NOT_FOUND
{
  "success": false,
  "message": "The specified job could not be found.",
  "error": {
    "detail": "No job with id 'job_xyz999' exists.",
    "code": "JOB_NOT_FOUND"
  }
}
The job_id does not match any job in the system. Verify the ID. Jobs are not deleted while they are active, but completed job records may be evicted from Redis after the configured TTL.
Error code: JOB_ALREADY_PROCESSING
{
  "success": false,
  "message": "A job for this video is already in progress.",
  "error": {
    "detail": "Job 'job_abc123' is currently processing video 'vid_abc123'.",
    "code": "JOB_ALREADY_PROCESSING"
  }
}
You attempted to submit a duplicate job for a video that is currently being processed. Wait for the existing job to complete or fail before submitting a new one. Poll GET /api/v1/jobs/{job_id} to check status.

​
Timeout errors

Error code: JOB_TIMEOUT
{
  "success": false,
  "message": "The job exceeded the maximum processing time and was terminated.",
  "error": {
    "detail": "Job ran for 3601 seconds, exceeding the limit of 3600 seconds.",
    "code": "JOB_TIMEOUT"
  }
}
The job ran longer than PROCESSING_TIMEOUT_SECONDS and was forcibly stopped. The job will not retry automatically.To resolve:
  1. Check whether the video is unusually long. Very long videos may legitimately require more time.
  2. Ask your administrator to increase PROCESSING_TIMEOUT_SECONDS if the timeout is too aggressive.
  3. Re-submit the job once the timeout has been adjusted.
If a particular video consistently times out, try trimming it to the relevant section before uploading. Speech recognition and visual embedding are the most time-intensive stages.

​
Result not ready

Error code: JOB_NOT_COMPLETE
{
  "success": false,
  "message": "The job has not finished processing.",
  "error": {
    "detail": "Job 'job_abc123' is currently in status 'processing'.",
    "code": "JOB_NOT_COMPLETE"
  }
}
You requested results before the job finished. Check the job status before fetching results:
GET /api/v1/jobs/{job_id}
Only fetch results once the status is completed. Implement polling with a reasonable interval (5–15 seconds) rather than requesting results immediately after submission.

​
Webhook delivery failure

Error code: WEBHOOK_DELIVERY_FAILEDClipzy logs webhook delivery failures but does not surface them as API errors — the job itself may have completed successfully.Common causes:
  • Your webhook endpoint returned a non-2xx status code
  • Your endpoint was unreachable or timed out during delivery
  • TLS certificate errors on your endpoint
To diagnose:
  1. Check your webhook endpoint’s access logs for incoming requests from Clipzy.
  2. Ensure your endpoint returns a 200 OK within 10 seconds of receiving the request.
  3. Verify your endpoint’s TLS certificate is valid and trusted.
Clipzy retries webhook delivery up to 3 times with exponential backoff. If all retries fail, poll GET /api/v1/jobs/{job_id} directly to retrieve the result.