# 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](https://docs.platform.pixverse.ai/error-codes-2394992m0) for numeric error codes, and [Task status](https://docs.platform.pixverse.ai/query-task-status-2394991m0) for task states and how to check them.

```json
{
  "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`.

```json
{
  "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`.

```json
{
  "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`.

```json
{
  "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.

```json
{
  "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. |