Errors

Error codes and handling for generations and assets.

Check the HTTP status first, then the error code. message is a readable description; details provides additional information, such as field errors or related resource IDs. Use code for programmatic handling and allow for unknown codes.

Generation request errors

Failed requests return an error object directly:

json

{
  "code": "invalid_parameter",
  "message": "Invalid parameter 'duration': must be a positive integer in seconds.",
  "details": { "duration": "must be a positive integer in seconds" }
}

code and message are strings. details is an optional object with string keys and values. Parameter errors typically use field paths as keys, such as duration or parts[1].image.assetId.

If a failed creation response includes details.generation_id, use it to retrieve the generation. Moderation errors may also include asset_id and field.

HTTP	`code`	Cause and action
400	`invalid_request`	Invalid JSON or request format. Correct the request.
400	`invalid_parameter`	Missing parameters, invalid types, or an unsupported combination. Check `details`.
400	`model_not_supported`	Unsupported model. Check `model`.
400	`content_policy_violation`	Content did not pass moderation. Revise the prompt or image.
400	`invalid_image`	Invalid image content, format, or dimensions. Use another image.
400	`image_too_large`	Image exceeds the size limit. Reduce its size.
400	`invalid_image_url`	URL does not meet the public HTTPS requirements. Correct the URL.
400	`image_unavailable`	Image could not be retrieved. Check the URL, access permissions, and expiration.
400	`insufficient_credits`	Insufficient available credits. Add credits before submitting.
401	`invalid_api_key`	Missing or invalid API key. Check the key and Authorization header.
403	`organization_banned`	Organization is suspended.
403	`permission_denied`	Organization does not have access to this model.
404	`asset_not_found`	Starting image asset is missing, deleted, or belongs to another organization.
404	`generation_not_found`	Generation is missing, deleted, or belongs to another organization.
429	`rate_limit_exceeded`	Request rate exceeded. Reduce the request frequency.
500	`internal_error`	Internal error. Follow the retry guidance.
503	`service_unavailable`	Service is temporarily unavailable. Follow the retry guidance.

Unknown endpoints, unsupported methods, an Accept header that excludes JSON, and unsupported content types return 404, 405, 406, and 415, respectively, with code invalid_request. A 405 response includes Allow; a 401 response includes WWW-Authenticate: Bearer.

Generation failures

Retrieving a failed generation still returns HTTP 200. Its status is failed, and error contains the failure reason:

json

{
  "code": "generation_failed",
  "message": "Video generation failed."
}

`error.code`	Meaning
`generation_failed`	Video generation failed.
`generation_timeout`	Generation exceeded the allowed processing time.
`content_policy_violation`	Input or output did not pass moderation.
`service_unavailable`	Processing or moderation service is temporarily unavailable.
`insufficient_credits`	Insufficient credits during processing.

Polling does not restart a failed generation. To try again, address the cause and create a new generation.

Asset errors

json

{
  "code": "00200",
  "message": "Unknown file extension: gif",
  "details": null
}

Asset error codes are numeric strings; preserve their leading zeros. details is a nullable object with string keys and values. Moderation errors may include assetId and errorCode.

HTTP	`code`	Cause and action
400	`00003`	Invalid parameters, filename, or path ID, or image moderation failed. Check the input.
400	`00200`	Unsupported file extension. Use a supported format.
400	`00202`	File is empty, cannot be decoded, or has invalid dimensions or duration. Use another file.
400	`00204`	Upload exceeds the size limit. Reduce the file size.
401	`00001`	Missing or invalid API key. Check authentication.
403	`00002`	Organization is suspended or cannot access the asset.
404	`00005`	Asset is missing or deleted.
429	`00009`	Request rate exceeded. Reduce the request frequency.
500	`00006`	Internal processing error.
503	`00006`	Service is temporarily unavailable.

An unsupported Content-Type may return 415 / 00003; an unsupported HTTP method returns 400 / 00010. See Upload an Asset for file requirements.

For troubleshooting, retain the endpoint, request time, HTTP status, error code, and generation or asset ID. Do not log API keys.