Error envelope
json
{
"error": {
"code": "invalid_request",
"message": "The request is invalid",
"request_id": "req-...",
"details": [
{
"path": "parameters.duration_seconds",
"code": "too_big",
"message": "Number must be less than or equal to 30"
}
]
}
}Log request_id and include it when contacting support. Never parse human-readable messages as stable program logic.
HTTP errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed JSON, invalid fields, or an invalid constraint combination |
| 401 | authentication_required | Bearer key missing, invalid, expired, or inactive |
| 402 | insufficient_balance | Not enough available balance |
| 403 | forbidden / model_not_available | The key lacks the required scope or the project cannot use the model |
| 404 | generation_not_found / media_asset_not_found | The resource does not exist in this project |
| 409 | idempotency_conflict / media_upload_not_ready / media_asset_not_ready | Request conflicts with current state |
| 410 | media_upload_expired | The reserved upload expired |
| 413 | payload_too_large / media_upload_limit_exceeded | HTTP or media-upload limit exceeded |
| 415 | unsupported_media_type | Request Content-Type is not application/json |
| 422 | media_upload_mismatch / input_video_duration_invalid | Uploaded metadata or verified duration violates the contract |
| 422 | input_media_dimensions_invalid | Verified Seedance image/video dimensions violate the model limits; details identifies the file, dimensions and limits. No generation or balance reservation is created. |
| 503 | media_upload_storage_unavailable | File verification is temporarily unavailable |
| 500 | internal_error | Internal server error |
Asynchronous generation failures
If an error occurs after creation, GET returns HTTP 200, status: failed, and an error object. Treat unknown asynchronous error codes as valid and display the message or contact support.
Branch on error.code, not the message or an upstream HTTP status mentioned in it. A provider HTTP 400 alone does not mean content moderation.
| Code | Meaning | Next step |
|---|---|---|
| moderation_blocked / content_policy_violation | Provider content policy rejected the image request | Do not automatically repeat the same prompt; revise the request. A definitive rejection releases the reservation. |
| invalid_parameter / openai_http_400 / openai_http_422 | Provider rejected request parameters | Review model parameters; do not retry the identical request automatically. |
| provider_submission_unknown | The provider may have accepted the request, but the outcome is unknown | Do not create a duplicate generation. Keep the generation ID and contact support. |
| billing_reconciliation_required | Usage or billing needs verification | Keep polling the existing generation; do not assume the reservation has been refunded. |
These are common codes, not an exhaustive enumeration of provider errors. Unknown codes must not crash the client. Record the generation ID and request ID. Statuses submission_unknown and billing_reconciliation are unresolved states, not a confirmed failure or a signal to create a new paid request.