Error Details

Error explains what went wrong and how to resolve it in more detail than a numeric error code alone. This optional object supplements ErrCode, ErrMsg, and Resp without changing the HTTP status. You can keep your existing error handling, and no additional request header is required.

See Error codes for numeric error codes, and Task status for task states and how to check them.

{
  "ErrCode": 400017,
  "ErrMsg": "Required field prompt are missing or empty.",
  "Resp": null,
  "Error": {
    "Type": "FIELD_REQUIRED",
    "Message": "Required field 'prompt' is missing or empty. Provide a value for this field.",
    "Param": {
      "Fields": [
        "prompt"
      ]
    }
  }
}

Error fields

Check whether the request failed as you normally would. If the response includes Error, use Error.Type to identify the problem, then read Error.Message and Error.Param for details. If Error is missing, use the numeric error code as usual. A response without Error is not necessarily successful.

Field	Purpose
`Error.Type`	A stable error identifier. Several types can share the same numeric error code.
`Error.Message`	An explanation of the error and what to do next. Use `Error.Type` to identify errors rather than matching this text.
`Error.Param`	Additional details about the error. This is always an object, or `{}` when no reliable details are available.

Your client should accept additional response fields. If it receives an unfamiliar Type, handle it as a general error and keep the response for troubleshooting.

Error.Param

Field	Type	Meaning
`Fields`	string[]	Names of the request fields that need attention, such as `["prompt"]`.
`AllowedValues`	string[]	Values supported for this request. Only used for `quality`, `aspect_ratio`, and `duration`; duration values are returned as strings.
`RequiredField`	string	The request field to use in place of the one supplied, such as `img_id`.
`RequiredCount`	integer	The number of inputs required by the selected template, such as `2`.
`Moderation.LabelName`	string	An explanation of why the content did not pass moderation, when available. Multiple explanations are separated by newlines.

Only fields relevant to the error are returned. Use the values in the response and the endpoint reference; a missing field does not imply a default value.

Below are several common error response examples for reference.

Invalid field value

In this example, the value of quality is not supported by the endpoint. Fields names the field to change; choose a supported value from AllowedValues.

{
  "ErrCode": 400017,
  "ErrMsg": "invalid param",
  "Resp": null,
  "Error": {
    "Type": "FIELD_VALUE_INVALID",
    "Message": "Field 'quality' has an unsupported value. Check the allowed values and format for this endpoint.",
    "Param": {
      "AllowedValues": ["360p", "480p", "540p", "720p", "1080p"],
      "Fields": ["quality"]
    }
  }
}

Supported values depend on the endpoint and request settings. AllowedValues may not be returned if the API cannot provide a complete list.

Incorrect field selection

Here, the request uses img_ids without selecting a multi-image template. To submit a single image, use img_id, as specified by RequiredField.

{
  "ErrCode": 400017,
  "ErrMsg": "img_ids is not supported in this case. Please use `img_id` instead.",
  "Resp": null,
  "Error": {
    "Type": "MULTI_IMAGE_INPUT_UNSUPPORTED",
    "Message": "Field 'img_ids' requires a multi-image template, but 'template_id' is missing or '0'. Replace 'img_ids' with 'img_id' for one image, or set 'template_id' to a multi-image template and supply its required number of image IDs in 'img_ids'.",
    "Param": {
      "Fields": ["img_id", "img_ids", "template_id"],
      "RequiredField": "img_id"
    }
  }
}

Incorrect input count

Here, img_ids contains one image ID, but the selected template needs two. Add another image ID to reach the number in RequiredCount.

{
  "ErrCode": 400017,
  "ErrMsg": "For the selected template_id, the img_ids array must contain 2 image（s）.",
  "Error": {
    "Type": "TEMPLATE_IMAGE_COUNT_MISMATCH",
    "Message": "The selected template requires exactly '2' image IDs in 'img_ids'. Adjust the array length to match this count.",
    "Param": {
      "Fields": ["img_ids", "template_id"],
      "RequiredCount": 2
    }
  }
}

Use the number in the response for your template; 2 is only an example.

Content rejected by moderation

In this example, the uploaded image did not pass content moderation. Moderation.LabelName explains why, in English.

{
  "ErrCode": 500063,
  "ErrMsg": "The uploaded image is not compliant, please replace it and try again",
  "Error": {
    "Type": "IMAGE_CONTENT_REJECTED",
    "Message": "The supplied image did not pass content moderation. Moderation reason: 'Sexual content: This content may involve sexual material.'. Replace the image and try again.",
    "Param": {
      "Moderation": {
        "LabelName": "Sexual content: This content may involve sexual material."
      }
    }
  },
  "Resp": null
}

Multiple explanations are separated by newlines. When no explanation is available, the response leaves out Moderation and keeps the general rejection message. Do not use the exact wording to identify the error, and do not assume the content was approved when no explanation is returned.

Error.Type index

Find the response's Error.Type value below, such as FIELD_REQUIRED, to see what it means and what to do next.

`Error.Type`	Description	What to do
`API_KEY_INVALID`	The API key could not be verified.	Check the key and make sure you are using the correct API endpoint.
`API_KEY_REQUIRED`	The `API-KEY` header is missing.	Include your key in the `API-KEY` header.
`AUDIO_CONTENT_REJECTED`	The supplied audio did not pass content moderation.	Replace the audio and submit the request again.
`AUDIO_DURATION_BELOW_THRESHOLD`	The audio is too short.	Use audio that meets the duration requirements in `Message`. Requirements vary by endpoint and model.
`CAMERA_MOVEMENT_MODEL_UNSUPPORTED`	The selected model does not support this camera movement.	Check `Message` and use a camera movement supported by the selected model.
`CLIENT_REQUEST_CANCELED`	The client canceled the request.	Check your client's timeout and cancellation settings. Before submitting again, check whether a task was created.
`CONCURRENCY_LIMIT_EXCEEDED`	The account has reached its limit for simultaneous generation tasks.	Wait for a running task to finish before submitting another.
`DURATION_OUT_OF_RANGE`	The requested duration is outside the supported range.	Choose a duration within the range in `Message`. The range depends on the endpoint and model.
`EFFECT_QUALITY_UNSUPPORTED`	The effect does not support the selected quality.	Check the template settings and `Message`, then adjust the inputs, endpoint, or generation options.
`EXTENDED_DURATION_EXCEEDS_THRESHOLD`	The source video and extension together exceed the duration limit.	Adjust the duration to meet the requirements in `Message`. The limit depends on the endpoint and model.
`FEATURE_ACCESS_DENIED`	The account does not have access to this feature.	Contact support to request access.
`FIELD_REQUIRED`	A required field is missing or empty.	Fill in the fields listed in `Param.Fields` or named in `Message`.
`FIELD_VALUE_INVALID`	A field has an unsupported value or format.	Use a value from `Param.AllowedValues` when it is provided, and check the required format.
`FUSION_INPUT_REQUIRED`	No image or video reference was provided.	Provide a file, URL, or media ID as required by the endpoint.
`IMAGE_CONTENT_REJECTED`	The supplied image did not pass content moderation.	Replace the image and submit the request again.
`IMAGE_DIMENSIONS_BELOW_THRESHOLD`	The image dimensions are below the minimum.	Use an image that meets the dimensions in `Message`. Requirements vary by endpoint and model.
`IMAGE_DIMENSIONS_EXCEED_THRESHOLD`	The image dimensions exceed the limit.	Use an image within the dimensions given in `Message`. The limit depends on the endpoint and model.
`IMAGE_FORMAT_UNSUPPORTED`	The uploaded image format is not supported.	Convert the image to a supported format and upload it again.
`IMAGE_INPUT_REQUIRED`	No image file or image URL was provided.	Provide a file, URL, or media ID as required by the endpoint.
`IMAGE_REFERENCE_COUNT_EXCEEDS_THRESHOLD`	Too many image references were provided for the selected model.	Reduce the number of references to meet the requirements in `Message` for the endpoint and model.
`IMAGE_REFERENCE_REQUIRED`	A required image reference is missing.	Provide a file, URL, or media ID as required by the endpoint.
`IMAGE_SIZE_EXCEEDS_THRESHOLD`	The image file exceeds the size limit.	Use an image within the size limit given in `Message` for the endpoint and model.
`INPUT_KEY_DUPLICATED`	More than one template input uses the same `input_key`.	Use each `input_key` only once.
`INPUT_KEY_REQUIRED`	A template input is missing `input_key`.	Set `input_key` to a value from the template's `input_limit`.
`INSUFFICIENT_CREDITS`	The account does not have enough credits for this request.	Add credits or choose settings that use fewer credits.
`MEDIA_ACCESS_DENIED`	The account does not have access to the referenced media.	Use media that this account can access.
`MEDIA_FORMAT_UNSUPPORTED`	The media at the URL is not in a supported format.	Convert the file to a supported format and upload it again.
`MEDIA_INPUT_REQUIRED`	No media file or media URL was provided.	Provide a file, URL, or media ID as required by the endpoint.
`MEDIA_NOT_FOUND`	The referenced media could not be found.	Check that the media ID and type are correct and the media is available for this endpoint.
`MEDIA_TYPE_MISMATCH`	The referenced media has the wrong type for this endpoint.	Check the media ID and type, and use available media that the endpoint supports.
`MEDIA_UNAVAILABLE`	The referenced media cannot be used for this operation.	Check the media ID, type, and availability, and use media that the endpoint supports.
`MEDIA_URL_INVALID`	The media URL is invalid.	Check that the URL is valid and publicly accessible, or replace it.
`MIMIC_VIDEO_DURATION_OUT_OF_RANGE`	The motion reference video is outside the supported duration range.	Use a reference video within the duration range in `Message` for the endpoint and model.
`MODIFY_VIDEO_DURATION_OUT_OF_RANGE`	The source video is outside the duration range supported by Modify.	Use a source video within the duration range in `Message` for the endpoint and model.
`MOTION_MODE_MODEL_UNSUPPORTED`	The selected model does not support this motion mode.	Check `Message` and use a motion mode supported by the selected model.
`MULTI_IMAGE_INPUT_UNSUPPORTED`	The selected template or mode does not accept `img_ids`.	Use `img_id` for a single image, or select a multi-image template and provide the required number of images.
`OPTION_MODEL_UNSUPPORTED`	The selected model does not support this option.	Check `Message` and use an option supported by the model.
`PARAMETER_COMBINATION_UNSUPPORTED`	The selected generation options cannot be used together.	Check `Message` and choose a combination supported by the endpoint and model.
`PLAN_RESOLUTION_RESTRICTED`	The selected resolution exceeds the plan limit.	Choose a supported resolution or upgrade your plan.
`PROMPT_REFERENCE_SYNTAX_INVALID`	A reference in the prompt has invalid syntax.	Use `@ref_name` followed by a space.
`PROMPT_REFERENCE_UNDEFINED`	A reference in the prompt has no matching `ref_name`.	Match the prompt references to the supplied `ref_name` values, or remove the unmatched references.
`QUALITY_DURATION_EXCEEDS_THRESHOLD`	The duration is too long for the selected quality.	Choose a duration within the limit in `Message` for the selected quality, endpoint, and model.
`QUALITY_DURATION_MODEL_UNSUPPORTED`	The selected model does not support this combination of quality and duration.	Check `Message` and choose quality and duration settings supported by the model.
`QUALITY_UNSUPPORTED`	The selected quality is not supported for this operation.	Choose a quality supported by the endpoint and model, as described in `Message`.
`RATE_LIMIT_EXCEEDED`	Requests are being sent too frequently.	Reduce the request rate and wait before trying again.
`REFERENCE_NAME_DUPLICATED`	More than one reference uses the same name.	Give each reference a unique `ref_name`.
`REMOTE_MEDIA_UNAVAILABLE`	The media at the URL is missing or cannot be accessed.	Check that the URL is valid and publicly accessible, or replace it.
`REQUEST_BINDING_FAILED`	The request body could not be read or did not meet the endpoint requirements.	Check the request format, field types, and required fields.
`REQUEST_FIELD_TYPE_INVALID`	A field has the wrong JSON type.	Use the JSON type in the endpoint reference. For example, send numbers without quotes.
`REQUEST_JSON_INVALID`	The request body is not valid JSON.	Correct the JSON syntax and submit the request again.
`SINGLE_IMAGE_INPUT_UNSUPPORTED`	The multi-image template does not accept `img_id`.	Use `img_ids` and provide the number of images the template requires. If `Param.RequiredField` is returned, use it to confirm which field to send.
`SYSTEM_ERROR`	The service encountered an error while processing the request.	Try again later. If the problem continues, contact support with the `Ai-trace-id` and task ID, if available.
`TEMPLATE_AUDIO_OPTION_CONFLICT`	The selected audio option cannot be used with this template.	Check the template settings and `Message`, then adjust the inputs, endpoint, or generation options.
`TEMPLATE_ENDPOINT_MISMATCH`	The template requires a different endpoint.	Submit the template and its inputs to the endpoint specified in `Message`.
`TEMPLATE_FEATURE_UNSUPPORTED`	The template does not support this generation feature.	Check the template settings and `Message`, then adjust the inputs, endpoint, or generation options.
`TEMPLATE_IMAGE_COUNT_MISMATCH`	The number of images does not match the template requirement.	Adjust the image count to match the template requirements. If `Param.RequiredCount` is returned, use that count.
`TEMPLATE_IMAGE_INPUT_REQUIRED`	A required image input is missing from the template request.	Provide a valid `img_id` for each required image input.
`TEMPLATE_INPUT_TYPE_CONFLICT`	A template image input contains fields for a different media type.	Remove the fields that do not apply to image inputs.
`TEMPLATE_MEDIA_TYPE_MISMATCH`	The template produces a media type that does not match the endpoint.	Check the template settings and `Message`, then adjust the inputs, endpoint, or generation options.
`TEMPLATE_UNAVAILABLE`	The template is not enabled.	Choose an enabled template, or contact support.
`TEXT_CONTENT_REJECTED`	The supplied text did not pass content moderation.	Revise the text and submit the request again.
`TEXT_LENGTH_EXCEEDS_THRESHOLD`	A text field exceeds the length limit.	Shorten the text to the limit given in `Message`.
`VIDEO_CONTENT_REJECTED`	The supplied video did not pass content moderation.	Replace the video and submit the request again.
`VIDEO_DIMENSIONS_EXCEED_THRESHOLD`	The video resolution exceeds the limit.	Use a video within the resolution limit in `Message` for the endpoint and model.
`VIDEO_DURATION_EXCEEDS_THRESHOLD`	The input video exceeds the duration limit.	Use a video within the duration limit in `Message` for the endpoint and model.
`VIDEO_ID_INVALID`	The video ID is not a valid positive numeric ID.	Use a positive `video_id` returned by a video generation endpoint.
`VIDEO_INPUT_REQUIRED`	No source video ID was provided.	Provide a file, URL, or media ID as required by the endpoint.
`VIDEO_REFERENCE_TOTAL_DURATION_EXCEEDS_THRESHOLD`	The combined duration of the reference videos exceeds the limit.	Reduce the total duration to meet the limit in `Message` for the endpoint and model.
`VIDEO_SIZE_EXCEEDS_THRESHOLD`	The video file exceeds the size limit.	Use a video within the size limit in `Message` for the endpoint and model.

Error fields#

Error.Param#

Error.Type index#

Error fields

Error.Param

Error.Type index