Error Codes

API gateway response formats, common HTTP status codes, and the values of the type and code fields in error responses.

Error responses from the API gateway follow the OpenAI-compatible format: the HTTP status code expresses the broad category, while error.type and error.code in the response body provide machine-actionable details.

Error response format

Inference endpoints (chat, image, video, audio, etc.) return a non-200 HTTP status code with this body:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": ""
  }
}

Field	Type	Description
`message`	string	Human-readable description; may be translated based on request language
`type`	string	Broad category derived from the HTTP status code; see type values
`code`	string	Specific error code; see code values; may be an empty string for some errors
`param`	string	Related request parameter name; usually empty

Management endpoints (console APIs under /api/) behave differently: business errors usually still return HTTP 200, distinguished by the success field:

{
  "success": false,
  "message": "error description",
  "data": null
}

The Seedance asset library uses a ResponseMetadata.Error envelope; see Seedance Asset Library.

HTTP status codes

Status	Meaning	Common causes
`200`	Success	Request completed; management endpoints also return 200 for business errors
`400`	Bad request	Body is not valid JSON, missing required parameters, invalid parameter values
`401`	Unauthenticated	API key missing, invalid, or disabled
`403`	Forbidden	Key has no access to the model/group, IP not in the token allowlist, user banned, or insufficient quota
`404`	Not found	Request path does not exist, or the async task ID does not exist
`408`	Request timeout	Upstream processing timed out
`413`	Payload too large	Exceeds the 256 MB request-body limit; error code `request_too_large`
`429`	Rate limited	Global rate limit or model RPM/TPM limit hit; slow down and retry
`500`	Internal error	Gateway internal error
`501`	Not implemented	The gateway does not support this endpoint path; error code `api_not_implemented`
`502` / `503`	Upstream error	The upstream model provider returned an error or is unavailable
`504`	Upstream timeout	The upstream model provider timed out

type values

error.type is derived from the HTTP status code and is a stable category:

type	Status codes	Description
`authentication_error`	401	Authentication failed; check that the API key is correct and enabled
`permission_error`	403	No access permission or insufficient quota
`rate_limit_error`	429	Rate limit triggered
`timeout_error`	408, 504	Request or upstream response timed out
`not_implemented_error`	501	Endpoint not implemented
`invalid_request_error`	Other 4xx	Request parameter error
`server_error`	5xx	Gateway or upstream service error
`upstream_error`	—	Fallback when an upstream error carries no type

code values

error.code is a more specific, machine-readable error code. Common values are listed below.

Authentication and permission

code	Description
`invalid_api_key`	API key missing, invalid, or deleted (default code for 401)
`access_denied`	No access to the requested resource, group, or agent domain

Request parameters

code	Description
`invalid_request`	Request parameter error (default code for 400)
`invalid_json`	Request body is not valid JSON
`invalid_type`	Field type error
`missing_parameter`	A required parameter is missing
`bad_request_body`	Request body does not meet endpoint requirements
`read_request_body_failed`	Failed to read the request body
`convert_request_failed`	Failed to convert the request format
`request_too_large`	Request body exceeds the 256 MB limit (HTTP 413)
`remote_fetch_failed`	Failed to fetch a remote file in the request (e.g. an image URL)
`unsupported_response_format`	Unsupported response format parameter

Models and channels

code	Description
`model_not_found`	The requested model does not exist or is not available to this token
`prompt_blocked`	Prompt blocked by the upstream safety policy
`sensitive_words_detected`	Content triggered sensitive-word detection
`channel:no_available_key`	Channel has no available key
`channel:invalid_key`	Channel key is invalid
`channel:model_mapped_error`	Model mapping configuration error
`channel:param_override_invalid`	Channel parameter-override configuration is invalid
`channel:header_override_invalid`	Channel header-override configuration is invalid
`channel:aws_client_error`	AWS channel client error
`channel:response_time_exceeded`	Channel response time exceeded the limit

channel:* errors mean a specific upstream channel failed. The gateway usually retries on another channel automatically; clients only see these errors when every available channel has failed.

Upstream responses

code	Description
`bad_response_status_code`	Upstream returned an unexpected status code
`bad_response`	Upstream response could not be processed
`bad_response_body`	Failed to parse the upstream response body
`read_response_body_failed`	Failed to read the upstream response
`empty_response`	Upstream returned an empty response
`aws_invoke_error`	AWS model invocation failed

Billing and quota

code	Description
`insufficient_user_quota`	Account quota is insufficient; top up and retry (HTTP 403)
`pre_consume_token_quota_failed`	Pre-consumption failed, usually because quota cannot cover the estimated cost of this request (HTTP 403)

Internal system

code	Description
`unknown_error`	Uncategorized error
`count_token_failed`	Token counting failed
`model_price_error`	Model pricing configuration error
`invalid_api_type`	Internal API type error
`json_marshal_failed`	Internal serialization failed
`do_request_failed`	Failed to send the request to the upstream
`get_channel_failed`	Failed to obtain an available channel
`gen_relay_info_failed`	Failed to generate relay information
`query_data_error`	Data query failed
`update_data_error`	Data update failed

Async task errors

Async task endpoints (e.g. Seedance and Kling video generation) can return the errors above when a task is created. Once a task is created, a processing failure does not change the HTTP status of the task query endpoint; it is reported in the error field of the task result instead:

{
  "id": "task-id",
  "status": "failed",
  "error": {
    "code": "upstream error code",
    "message": "failure reason"
  }
}

When polling a task, rely on the status field and read error when it becomes failed.

Troubleshooting

401: confirm the Authorization: Bearer <key> header is correct and the key has not been deleted or disabled.
403: check model access, token group, IP allowlist, and account quota in order.
429: reduce concurrency and request rate; retry with exponential backoff.
5xx: the gateway already retries retryable errors on other channels; if failures persist, contact the platform with the message content.
Error messages may be translated based on request language. For programmatic handling, match on type and code, never on the message text.

Error Codes

On this page