Error Codes

Error Handling

When a request fails, first check the HTTP status code to identify the type of problem, then check the code and message in the response body to pinpoint the specific cause. This document explains what common errors mean, whether they are safe to retry, and the recommended way to handle them.

Error Response Structure

When a request fails, the API typically returns JSON like the following:

json

Copy

{
  "code": 1000,
  "message": "Duration must be between 1 and 6 seconds."
}

Field	Type	Description
`code`	number	Business error code
`message`	string	Specific error description
`data`	object	Additional data; returned when supplementary information is available

Handling Principles

HTTP Status Code	Error Type	Retry Recommended	How to Handle
`400`	Parameter error	No	Fix the request parameters and resubmit
`401`	Authentication error	No	Check the token, signature, expiration time, and request headers
`403`	Permission or credit-package error	No	Check account entitlements, credit packages, and credits
`404`	Resource not found	No	Check whether the `task_id`, `batch_id`, or resource is incorrect or has expired
`429`	Quota or rate limiting	Yes	Verify entitlement quotas, queue capacity, and concurrency limits; monitor request frequency, and if you find high-frequency access above the limit, consider lowering your request concurrency threshold
`500`	Server error	Yes	Retry later; if failures persist, contact support

For 429 and transient 5xx errors, we recommend exponential backoff — for example, waiting 2, 4, then 8 seconds — with a maximum retry count. Never auto-retry parameter errors or authentication errors.

Common Error Codes

HTTP Status Code	Business Code	Description	Recommended Action
`200`	`200`	Success	Request succeeded
`400`	`1000`	Parameter information exception.	Check `message` and fix the parameters
`400`	`1001`	Contains sensitive information.	Modify the input to remove sensitive or non-compliant content
`401`	`1100`	Authentication Failed.	Check whether the token is correct
`401`	`1101`	Authorization header is missing.	Add `Authorization` to the request headers
`401`	`1102`	Authorization not yet valid.	Check the token's `nbf` time; wait for it to take effect or re-issue the token
`401`	`1103`	Authentication has expired.	Regenerate the token
`404`	`1200`	Invalid request. The requested resource does not exist or is not available.	Check whether the request path, task ID, or resource exists
`404`	`1203`	Batch ID does not exist or has expired.	Check whether the `batch_id` is correct or has expired
`403`	`1300`	Your credit package does not support this video duration.	Check whether your credit package supports this duration or has expired
`403`	`1301`	Your credit package does not support this video resolution.	Check whether your credit package supports this resolution or has expired
`403`	`1302`	Insufficient credit package.	Check your credits or credit-package balance
`429`	`1800`	Insufficient credit quota.	Reduce request frequency, increase your quota, or contact support
`500`	`5000`	Internal Server Error.	Retry later; if failures persist, contact support

Common Parameter Errors

When the HTTP status code is 400 and the business code is 1000, message describes the specific field problem.

General Parameters

Error Message	Cause	Resolution
`Model name is required.`	`model_name` is missing or empty	Provide a valid model name
`Prompt is required.`	`prompt` is missing	Provide a text prompt
`Duration must be between 1 and 6 seconds.`	Video duration is outside the range supported by the endpoint	Set the duration according to the specific API documentation
`Resolution must be 720p or 1080p.`	Invalid resolution format	Use `720p` or `1080p`
`Aspect ratio must be 16:9, 9:16, or 1:1.`	Invalid aspect ratio	Use an aspect ratio supported by the endpoint
`Seed must be between 0 and 10000000.`	Random seed out of range	Use an integer between `0` and `10000000`
`The prompt length must not exceed 10000 characters.`	Prompt is too long	Shorten it to within 10,000 characters
`The negative prompt length must not exceed 10000 characters.`	Negative prompt is too long	Shorten it to within 10,000 characters
`The audio prompt length must not exceed 200 characters.`	Audio prompt is too long	Shorten it to within 200 characters
`The callback url length must not exceed 500 characters.`	Callback URL is too long	Shorten it to within 500 characters
`Task Id is required.`	Task ID is missing	Use the `task_id` returned by the create-task endpoint

Images and Reference Inputs

Error Message	Cause	Resolution
`Image URL must be a valid HTTP or HTTPS URL`	Invalid image URL format	Provide a publicly accessible HTTP/HTTPS URL
`Image URL is required.`	Image URL is missing	Provide a valid image URL
`Image URL cannot be empty.`	Image URL is empty	Ensure the URL string is not empty
`Image URL list cannot exceed 9 elements.`	Number of images or reference inputs exceeds the limit	Keep the list to at most 9 elements
`Reference inputs cannot exceed 9 elements.`	Number of `reference_inputs` exceeds the limit	Provide at most 9 reference inputs
`URL array at index {n} cannot exceed 4 URLs.`	A URL array exceeds the limit	Each array may contain at most 4 URLs
`Images array must contain 2 to 4 URLs`	Number of subject reference images does not meet the requirement	`subject`-type inputs require 2 to 4 images of the same subject

File Upload

Error Message	Cause	Resolution
`The upload image list cannot be empty.`	Upload image list is empty	Provide at least one image
`The upload type cannot be empty.`	`upload_type` is missing	Use `url` or `base64`
`The upload type can only be url or base64.`	Invalid upload type	Use a publicly supported upload type
`Batch upload supports a maximum of {n} files.`	Number of batch-upload items exceeds the limit	Upload at most 300 images per batch
`The {n}th file: imageData cannot be empty.`	Image data is empty	Provide a valid image URL or Base64 data
`The {n}th image URL does not have a valid file extension.`	URL is missing a valid extension	Ensure the URL contains a supported image extension
`The {n}th image URL format '{ext}' is not supported.`	Unsupported image format	Use a supported image format
`The {n}th image (base64) size is approximately {size}MB, exceeds the maximum limit of 10MB.`	Base64 image is too large	Each image must not exceed 10MB
`The {n}th image (base64): Cannot determine image format.`	Base64 image format cannot be identified	Provide a `format` parameter or use a data URL
`The upload file list cannot be empty.`	File list is empty	Upload at least one file
`The {n}th file '{filename}' size is {size}MB, exceeds the maximum limit of 10MB.`	File is too large	Each image must not exceed 10MB
`The length of imageNames array must match the length of files array.`	Number of custom file names does not match	The number of `image_names` must match the number of `files`

Supported image formats: jpg, jpeg, png.

Subject Parameters

Error Message	Cause	Resolution
`Subject name is required.`	Subject name is missing	Provide a valid subject name
`The name length must not exceed 50 characters.`	Subject name is too long	Shorten it to within 50 characters
`The desc length must not exceed 500 characters.`	Subject description is too long	Shorten it to within 500 characters
`Subject type must be either 'character' or 'object'`	Invalid subject type	Use `character` or `object`

Troubleshooting Suggestions

Parameter errors: Check message first, then compare against the parameter description of the corresponding API.
Authentication errors: Confirm the token was correctly signed with your AccessKey and SecretKey and has not expired.
Task query failures: Confirm you are using the task_id returned by the create-task endpoint; do not mix in IDs from other endpoints.
Rate-limit errors: Reduce request frequency, configure exponential backoff and a maximum retry count; verify your entitlement package to confirm whether the quota is exhausted or the entitlement is unavailable.
Server errors: Record the request time, endpoint path, task_id, and error response to facilitate follow-up troubleshooting.

Callbacks

Text to Video

On this page