All errors return specific HTTP status codes and detailed error messages in the detail field.
Error Categories User Errors
Validation Errors
Content Errors
System Errors
Issues caused by invalid requests or insufficient resources.
HTTP Status: 402 Payment RequiredDescription: Not enough credits to complete the requestSolution: Add more credits to your account{ "detail" : "INSUFFICIENT_CREDITS" }
HTTP Status: 404 Not FoundDescription: Generation with specified ID does not existSolution: Verify the generation ID is correct{ "detail" : "Generation not found" }
HTTP Status: 401 UnauthorizedDescription: Token not provided, invalid, or expiredSolution: Include valid Bearer token in Authorization header{ "detail" : "Missing credentials" }
Issues with request parameters.
HTTP Status: 422 Validation ErrorDescription: Prompt is too short, too long, or missingSolution: Provide prompt with 1-4000 characters{ "detail" : [ { "type" : "string_too_short" , "loc" : [ "body" , "prompt" ], "msg" : "String should have at least 1 character" } ] }
HTTP Status: 422 Validation ErrorDescription: Orientation value is not “9:16” or “16:9”Solution: Use valid orientation value{ "detail" : [ { "type" : "enum" , "loc" : [ "body" , "orientation" ], "msg" : "Input should be '9:16' or '16:9'" } ] }
HTTP Status: 422 Validation ErrorDescription: Duration is not 10 or 15Solution: Use 10 or 15 for duration{ "detail" : [ { "type" : "enum" , "loc" : [ "body" , "duration" ], "msg" : "Input should be 10 or 15" , "input" : 5 } ] }
Both Image Methods Provided
HTTP Status: 400 Bad RequestDescription: Cannot use both image_base64 and image_url simultaneouslySolution: Choose one image input method{ "detail" : "Cannot provide both image_base64 and image_url" }
Issues with content during generation.
HTTP Status: Returned in status endpointDescription: Image contains photorealistic peopleSolution: Use different images or stylized portraits{ "status" : "failed" , "error_message" : "Image contains photorealistic people. Please try with a different image." }
HTTP Status: Returned in status endpointDescription: Content violates usage policiesSolution: Modify prompt to comply with content guidelines{ "status" : "failed" , "error_message" : "Content violates our usage policies" }
Technical issues on the server side.
HTTP Status: 500 Internal Server ErrorDescription: Unexpected error on the serverAction: Retry your request or contact support if the issue persists{ "detail" : "Internal server error" }
HTTP Status: 503 Service UnavailableDescription: Service is temporarily unavailableAction: Wait and retry your request later
HTTP Status: Returned in status endpointDescription: Generation exceeded maximum processing timeAction: Credits are automatically refunded{ "status" : "failed" , "error_message" : "Generation timeout exceeded" }
HTTP Status Code Reference Generation created successfully
Invalid parameters or request format
Invalid input format or missing required fields
Service temporarily unavailable
Common Error Scenarios Scenario 1: Insufficient Balance # Check balance before generation balance_response = requests.get( "https://platform.runblob.io/v1/data/balance" , headers = { "Authorization" : f "Bearer { token } " } ) balance = balance_response.json()[ "balance" ] if float (balance) < 0.12 : # Minimum for 10s video print ( "Insufficient balance. Please add credits." ) else : # Proceed with generation generate_video(prompt)
import base64 # Validate image before sending def validate_image ( file_path ): # Check file size file_size = os.path.getsize(file_path) if file_size > 10 * 1024 * 1024 : # 10 MB raise ValueError ( "Image too large. Max 10MB" ) # Check format valid_formats = [ '.jpg' , '.jpeg' , '.png' , '.webp' ] if not any (file_path.lower().endswith(fmt) for fmt in valid_formats): raise ValueError ( "Invalid format. Use JPEG, PNG, or WEBP" ) return True try : validate_image( "image.jpg" ) # Proceed with generation except ValueError as e: print ( f "Validation error: { e } " )
Scenario 3: Handling Failed Generations def check_generation ( generation_id ): response = requests.get( f "https://platform.runblob.io/v1/sora/generations/ { generation_id } /" , headers = { "Authorization" : f "Bearer { token } " } ) data = response.json() if data[ "status" ] == "failed" : error = data[ "error_message" ] # Handle specific errors if "photorealistic people" in error: print ( "Try with a different image without people" ) elif "policy" in error: print ( "Modify your prompt to comply with policies" ) else : print ( f "Generation failed: { error } " ) return None return data
Always implement proper error handling in your application to provide good user experience and handle edge cases gracefully.
