Errors

The API uses standard HTTP status codes and a consistent error object, so you can route failures quickly and recover with less guesswork.

Error response format

{
  "error": {
    "message": "Unsupported resolution '4K' for model 'seedream-5-lite'.",
    "type": "invalid_request_error",
    "param": "resolution",
    "code": "invalid_parameter"
  }
}

Field	Type	Description
`message`	string	Human-readable description of the error
`type`	string	Always `invalid_request_error`
`param`	string or null	The request parameter that caused the error, if applicable
`code`	string	Machine-readable error code
`doc_url`	string	Link to relevant documentation, when available

Error codes

Code	HTTP status	Description	Retryable
`invalid_api_key`	401	Missing, malformed, revoked, or invalid API key	No
`parameter_missing`	400	A required parameter was not provided	No
`invalid_parameter`	400	A parameter value is not supported for the selected model	No
`quota_exceeded`	402	Insufficient account balance or quota	No
`content_policy_violation`	422	Prompt or reference image input failed safety checks	No
`rate_limit`	429	Too many requests	Yes
`not_found`	404	The requested resource does not exist	No
`server_error`	500	Unexpected server-side error	Yes

Handling errors

Use the HTTP status code and error.code together. The status code tells you whether the failure is temporary. The error code tells you what to fix next.

Retryable failures

Retry 429 and 500 responses with exponential backoff.

For 429, wait for the Retry-After header.
For 500, use backoff with a timeout or retry limit.
Log the generation ID when you have one so you can trace the failed generation.

See Rate limits for details.

Terminal failures

Do not retry 400, 401, 402, 404, or 422 until you change the request or account state.

400: fix missing or invalid parameters
401: fix your API key
402: add credits or resolve quota limits
404: verify the resource ID or path
422: revise the prompt or reference image input

Async video failures

Video generations can fail after submission. When you poll GET /v2/videos/generations/{id}, the response can return status: "failed" with an error object.

{
  "id": "req-01HXYZVIDEO1234",
  "status": "failed",
  "error": {
    "message": "Upstream provider request timed out.",
    "code": "server_error"
  }
}

Treat failed as a terminal state for that generation. Read error.message, fix the input or retry policy, and submit a new generation when you’re ready. See Generate videos for a polling example.

Getting started

Generation

Concepts

Error response format

Error codes

Handling errors

Retryable failures

Terminal failures

Async video failures

​Error response format

​Error codes

​Handling errors

​Retryable failures

​Terminal failures

​Async video failures

Error response format

Error codes

Handling errors

Retryable failures

Terminal failures

Async video failures