Seedance Resource Management API Error Code Guide

Error code guide for the seedance resource management API, for API callers, organized by HTTP status code.

Response Format Conventions

• Management APIs (the /api/model-resources series) uniformly return HTTP 200 for business errors, and the response body contains only two fields:

  { "success": false, "message": "APIkey 对应的分组通道与资源分组不一致，请检查令牌的seedance分组！" }

• Management APIs do not return a code field; callers should rely on the Chinese hint in message.

• Task submission and resource reference APIs return errors with standard HTTP status codes (OpenAI-compatible format, including a code field).

• When a task is submitted successfully but generation fails, querying the task returns a task failure status code (see the appendix table at the end).

---

HTTP 200 · Business Errors (Resource Management APIs)

1. Authentication & Session

message	Reason	Solution
Session expired	Login state is invalid, or a management API was called without valid credentials	Log in again and retry, or switch to API Key authentication
The API Key does not belong to the current user	The API Key used in the request does not match the logged-in user	Use the current user's own API Key
The API Key does not exist or has been deleted	The API Key used has been deleted or is invalid	Regenerate an API Key and retry

2. Parameter Validation

message	Reason	Solution
Invalid resource group ID	group_id is not a positive integer, or the route :id is invalid	Check and correct the group_id parameter
Invalid resource ID	The uuid parameter is empty	Pass a valid resource UUID (starting with tkres_)
Resource group name cannot be empty	No name was passed when creating/updating a group	Add the name field
Resource group name cannot exceed 64 characters	The group name is too long	Shorten it to within 64 characters
Resource group description cannot exceed 300 characters	The group description is too long	Shorten it to within 300 characters
Resource name cannot be empty	No name was passed when creating/updating a resource	Add the name field
Resource name cannot exceed 128 characters	The resource name is too long	Shorten it to within 128 characters
Resource description cannot exceed 500 characters	The resource description is too long	Shorten it to within 500 characters
metadata is not valid JSON	The metadata field format is invalid	Pass a valid JSON string
Invalid resource_type	Only image/video/audio/document/archive/other are supported	Check the value
Invalid source_type	Only upload/model_generated/external_import are supported	Check the value
Invalid storage_type	Only local/s3/url/provider are supported	Check the value
busi_type only supports 0 (personal), 1 (organization), 2 (enterprise)	busi_type is out of range	Use 0/1/2
group_id is invalid	group_id is negative when updating a resource	Use a valid group ID
Synchronizing provider resources requires specifying group_id	No group was specified when creating a resource	Create a group first, then pass group_id
Synchronizing provider resources requires a url	The url is empty when creating a resource	Provide an accessible resource URL
Organization resources require organization_id	An organization-level resource is missing department ownership	Add organization_id, or use a personal resource

3. Data Not Found

message	Reason	Solution
Resource group does not exist	The group has been deleted or is not visible	Confirm the group ID, or query it via the list API
Resource does not exist	The resource has been deleted or is not visible	Confirm the UUID, or query it via the list API
Department does not exist	The specified department does not exist	Check organization_id

4. Permissions & Ownership

message	Reason	Solution
Only resource group creators may maintain it	Only the creator can modify/delete a group	Use the creator's account or API Key
No permission to maintain this resource group	Not the creator and not in the same tenant scope	Contact the administrator who owns the group
Only resource creators may maintain it	Only the creator can modify/delete a resource	Use the creator's account or API Key
No permission to maintain this resource	Not the creator and not in the same tenant scope	Contact the administrator who owns the resource
Resource reference requires API Key access	No API Key was carried	Switch to API Key authentication
API Key is missing department membership information	A department-member API Key is missing ownership info	Recreate/configure the API Key
API Key is missing enterprise or department ownership information	An enterprise-direct-connection Key is missing ownership info	Recreate/configure the API Key
API Key busi_type is invalid	The Key's business type is invalid	Recreate the API Key
User does not belong to the department	The user is not in the department member list	Join the department, or adjust the request scope
No permission to access this enterprise	The user has no permission to access the target enterprise	Request enterprise access permission
API Key is not bound to an available group	The Key is not bound to a model group	Bind a group to the Key in the admin console
APIkey 对应的分组通道与资源分组不一致，请检查令牌的seedance分组！	The provider of the available channel under the Key's group does not match the provider bound to the group	Use an API Key bound to the same provider, or put the resource into a group consistent with the Key's provider

5. Provider & Credential Configuration

message	Reason	Solution
Unconfigured enabled Volcano resource provider / no available Volcano/Doubao video channel under the group / channel has no resource provider configured	No provider configured, or no available channel under the Key's group	Contact the administrator to configure the provider and AK/SK
Resource provider configuration does not exist or is not enabled	The provider configuration is disabled or missing	Ask the administrator to enable the configuration
The channel associated with the resource provider does not exist	The associated channel has been deleted	Ask the administrator to rebind the channel
Remote sync of asset groups currently only supports the Volcano provider	Currently only the Volcano asset library is supported	Use the Volcano engine channel
The Volcano resource provider config is not valid JSON	The provider config is corrupted	Ask the administrator to fix the config
Volcano asset library AK/SK not configured	Neither the provider nor the channel has a valid AK/SK	Ask the administrator to configure the AK/SK
The channel associated with the resource provider has no valid Volcano AK/SK	No AK/SK can be parsed from the channel Key	Ask the administrator to check the channel credentials

6. Upstream Sync & Binding

message	Reason	Solution
The resource group is not bound to the corresponding provider group	The group has not completed its upstream binding	Recreate the group, or contact the administrator
Records already bound to a provider resource do not support modifying group_id	A resource bound to a provider cannot change groups	Create a new resource and specify the target group
The resource group is not bound to a Volcano group id	The upstream group id is missing when updating a group	Ask the administrator to check the binding data
The resource is not bound to a Volcano asset id	The upstream asset id is missing when updating a resource	Ask the administrator to check the binding data
The asset id returned by the Volcano asset library is empty	The upstream resource creation did not return an ID	Retry later; if it still fails, contact the administrator
The group id returned by the Volcano asset library is empty	The upstream group creation did not return an ID	Retry later; if it still fails, contact the administrator
The asset returned by the Volcano asset library is empty	The upstream status query returned empty	Retry later; if it still fails, contact the administrator
The Volcano asset library returned empty	The upstream API did not respond	Retry later; if it still fails, contact the administrator

7. Upstream Asset Library Passthrough Errors (within HTTP 200)

message	Reason	Solution
Volcano asset library call failed: {Code}	Volcano Ark API error (credentials/parameters/permissions)	Fix based on the upstream Message, or ask the administrator to check AK/SK permissions
Volcano asset library resource status query timed out: asset_id=xxx	The resource was not ready within 2 minutes	Check the status in the resource list later
Volcano asset library resource processing failed:	Upstream failed to process the asset	Check the resource URL and recreate it
Volcano asset library resource is available but the URL is empty: asset_id=xxx	Upstream anomaly	Ask the administrator to investigate

Note: Creating a resource is "persist first, sync asynchronously afterwards" — a failed upstream sync does not cause the create API to error, but instead shows up as status=failed, message=<failure reason> on the resource. Check it in the resource list.

---

HTTP 400 · Bad Request (seedance task submission)

The response is OpenAI-compatible and includes a code field.

code	message	Reason	Solution
invalid_request	Request body parsing failed	The request body is invalid JSON or missing required fields (such as prompt)	Check the request body format and required fields
invalid_multipart_form	multipart form parsing failed	The form format is incorrect	Check the file fields and request format

---

HTTP 403 · Forbidden (tkres_ resource reference)

code	message	Reason	Solution
access_denied	Resource {uuid} does not exist	The referenced resource UUID does not exist	Confirm the UUID via the resource list
access_denied	The API Key has no permission to use resource {uuid}	The resource ownership does not match the Key's tenant scope	Use a Key from the resource's tenant
access_denied	Resource {uuid} is not enabled	The resource is syncing or its sync failed	Wait until it is available, or check the resource message failure reason
access_denied	Resource {uuid} is not bound to the current channel	The current channel has no mapping for this resource	Use the channel corresponding to the resource's provider
access_denied	The provider resource ID of resource {uuid} is empty	The binding data is abnormal	Contact the administrator
access_denied	Resource reference requires API Key access	No API Key was carried	Switch to API Key authentication
access_denied	Resource reference replacement is missing channel_id	The request did not hit a valid channel	Check the model/channel configuration and retry

---

HTTP 500 · Internal Server Error (seedance task submission)

code	message	Reason	Solution
read_response_body_failed	Failed to read the upstream response	The upstream returned anomalies	Retry later; if it keeps failing, contact the administrator
unmarshal_response_body_failed	Failed to parse the upstream response	The upstream response format is abnormal	Retry later; if it keeps failing, contact the administrator
invalid_response	task_id is empty	The upstream did not return a valid task ID	Retry later; if it keeps failing, contact the administrator

---

Appendix: Task Failure Status Codes (returned when querying a task, not an API call error)

code	Message meaning	Reason	Solution
content_moderation	Content moderation failed	The prompt/asset hit the moderation rules	Modify the prompt or asset and retry
invalid_params	Invalid parameters	A parameter is not supported by the upstream	Adjust the parameter according to the error message
generation_failed	Generation failed	Upstream generation failed	Retry later
upload_failed	Upload failed	The asset upload failed	Check the asset URL and retry
model_unavailable	Model unavailable	The model resource is temporarily unavailable	Retry later, or contact the administrator
connection_failed	Connection failed	Anomaly connecting to the upstream	Retry later; if it keeps failing, contact the administrator
config_error	Configuration error	Upstream proxy/configuration anomaly	Contact the administrator
timeout	Task timed out	Upstream generation timed out	Retry later
auth_failed	Authentication failed	Upstream AK/SK authentication failed	Ask the administrator to check the credentials
rate_limited	Rate limited	Call frequency exceeded or upstream rate limiting	Reduce call frequency and retry