Skip to main content
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"
  }
}
FieldTypeDescription
messagestringHuman-readable description of the error
typestringAlways invalid_request_error
paramstring or nullThe request parameter that caused the error, if applicable
codestringMachine-readable error code
doc_urlstringLink to relevant documentation, when available

​
Error codes

CodeHTTP statusDescriptionRetryable
invalid_api_key401Missing, malformed, revoked, or invalid API keyNo
parameter_missing400A required parameter was not providedNo
invalid_parameter400A parameter value is not supported for the selected modelNo
quota_exceeded402Insufficient account balance or quotaNo
content_policy_violation422Prompt or reference image input failed safety checksNo
rate_limit429Too many requestsYes
not_found404The requested resource does not existNo
server_error500Unexpected server-side errorYes

​
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.