Errors

The VIDIO API uses a consistent error object format. Use this page to understand common error types, HTTP status codes, and example messages returned by the API.

API access is currently available for Enterprise plans only. Request access here if you are not an Enterprise user but are interested in using the API.

Overview

When a request fails, the VIDIO API returns an error object with a type and message. Some errors may also include additional fields to help explain the failure.

Error format

json

{
  "error": {
    "type": "invalid_request_error",
    "message": "Job not found"
  }
}

Error reference

Status	Type	Message	Description
400	invalid_request_error	Missing required query parameters in upload URL request	Returned when required query parameters are missing from the upload URL request.
400	invalid_request_error	Missing job_id	Returned when the render request does not include a job ID.
400	invalid_request_error	No outputs available for this job	Returned when the job does not have any renderable outputs.
400	invalid_request_error	input_keys must be a non-empty array	Returned when `input_keys` is missing or empty.
400	invalid_request_error	input_keys must contain at least one valid input key	Returned when all provided input keys are blank or invalid after normalization.
400	invalid_request_error	Invalid video_category. Allowed values: podcast, ball-sports, non-ball-sports, beauty-product-demo, wedding, travel, others	Returned when `video_category` is not supported.
400	invalid_request_error	Invalid aspect_ratio. Allowed values: square, portrait, landscape	Returned when `aspect_ratio` is not supported.
400	invalid_request_error	output_length must be a positive number	Returned when `output_length` is missing, zero, or negative.
400	invalid_request_error	Could not determine positive input duration from input_keys metadata	Returned when the API cannot determine a valid duration for the uploaded inputs.
401	authentication_error	Missing API key	Returned when the `x-api-key` header is not provided.
401	authentication_error	Invalid API key	Returned when the provided API key does not match an active key.
402	insufficient_balance	You do not have enough credits to process this job	Returned when the account does not have enough credits for processing or rendering.
403	permission_error	You do not have permission to access this job	Returned when the authenticated user does not own the requested job.
403	permission_error	You do not have permission to render this job	Returned when the authenticated user does not own the job being rendered.
404	invalid_request_error	Job not found	Returned when the requested job does not exist.
404	invalid_request_error	User not found	Returned when the authenticated user record cannot be found.
429	rate_limit_error	Too many requests	Returned when the client exceeds the allowed request rate for the endpoint. The current limit is 60 requests per minute. Rate limiting is primarily applied per API key using the x-api-key header, and falls back to the client IP address when an API key is not present. Clients that hit this limit should reduce request frequency and retry after the rate limit window resets.
500	api_error	Authentication error	Returned when API key authentication fails unexpectedly on the server.
500	api_error	Internal server error	Returned for unexpected server-side failures in status, render, or highlight reel endpoints.
500	server_error	Failed to generate upload URL	Returned when the server fails to generate a signed upload URL.