Error Handling

Comprehensive guide to VEO3 API error codes, troubleshooting, and proper error handling.

HTTP Status CodesError CodesAuto-Refunds

Error Response Format

All API errors follow a consistent JSON response format

Standard Error Format
{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": "Additional error details (optional)"
}
success: Always false for errors
error: Specific error code for programmatic handling
message: Human-readable description of the error
details: Optional additional context about the error

HTTP Status Codes

Standard HTTP status codes used by the VEO3 API

HTTP Status Codes
200
OK
Request successful
202
Accepted
Generation started (asynchronous)
400
Bad Request
Invalid parameters or request format
401
Unauthorized
Invalid or missing API key
402
Payment Required
Insufficient credits
404
Not Found
Task or resource not found
429
Too Many Requests
Rate limit exceeded
500
Internal Server Error
Server-side error

Common Error Codes

Detailed list of error codes with solutions

INVALID_API_KEY
API key is invalid or inactive
HTTP 401

Solution

Check your API key in the dashboard

INSUFFICIENT_CREDITS
Not enough credits for generation
HTTP 402

Solution

Purchase more credits or use a cheaper model

INVALID_PROMPT
Prompt is missing or invalid
HTTP 400

Solution

Provide a valid non-empty text prompt

INVALID_MODEL
Model name is not supported
HTTP 400

Solution

Use a valid model ID (veo-3.0-generate-preview or veo-3.0-fast-generate-preview)

MISSING_IMAGE
Image file is required for image-to-video
HTTP 400

Solution

Upload a valid image file (JPEG/PNG, max 20MB)

TASK_NOT_FOUND
Task ID doesn't exist or unauthorized
HTTP 404

Solution

Check task ID and ensure you own the task

VIDEO_NOT_READY
Video generation not completed
HTTP 400

Solution

Wait for completion or check status

NO_VIDEOS
No videos available for download
HTTP 404

Solution

Check generation status first

CONTENT_POLICY_VIOLATION
Content violates usage policies
HTTP 400

Solution

Modify your prompt to comply with content policies

GENERATION_FAILED
Video generation failed
HTTP 500

Solution

Try again or contact support (credits automatically refunded)

Error Response Examples

Real error response examples you might encounter

Invalid API Key
{
  "success": false,
  "error": "INVALID_API_KEY",
  "message": "The provided API key is invalid or inactive"
}
Insufficient Credits
{
  "success": false,
  "error": "INSUFFICIENT_CREDITS",
  "message": "Not enough credits to generate video",
  "required": 400,
  "available": 50
}
Content Policy Violation
{
  "success": false,
  "error": "CONTENT_POLICY_VIOLATION",
  "message": "Content violates usage policies",
  "details": "Prompt contains prohibited content"
}

Error Handling Best Practices

Implement robust error handling in your application

JavaScript Error Handling Example
async function generateVideo(prompt) {
  try {
    const response = await fetch('/api/veo/text-to-video', {
      method: 'POST',
      headers: {
        'X-API-Key': 'veo3_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ prompt })
    });

    if (!response.ok) {
      const error = await response.json();
      
      // Handle specific errors
      switch (error.error) {
        case 'INSUFFICIENT_CREDITS':
          showCreditPurchaseDialog();
          break;
        case 'CONTENT_POLICY_VIOLATION':
          showPromptHelp();
          break;
        case 'INVALID_API_KEY':
          redirectToLogin();
          break;
        default:
          showGenericError(error.message);
      }
      
      throw new Error(error.message);
    }
    
    return await response.json();
    
  } catch (error) {
    console.error('Video generation failed:', error);
    throw error;
  }
}
Python Error Handling Example
import requests
from requests.exceptions import RequestException

def generate_video(prompt, api_key):
    try:
        response = requests.post(
            'https://api.veo3gen.co/api/veo/text-to-video',
            headers={
                'X-API-Key': api_key,
                'Content-Type': 'application/json'
            },
            json={'prompt': prompt}
        )
        
        if not response.ok:
            error_data = response.json()
            error_code = error_data.get('error')
            
            # Handle specific errors
            if error_code == 'INSUFFICIENT_CREDITS':
                raise InsufficientCreditsError(error_data['message'])
            elif error_code == 'CONTENT_POLICY_VIOLATION':
                raise ContentPolicyError(error_data['message'])
            elif error_code == 'INVALID_API_KEY':
                raise AuthenticationError(error_data['message'])
            else:
                raise APIError(error_data['message'])
        
        return response.json()
        
    except RequestException as e:
        raise NetworkError(f"Network error: {e}")
    except ValueError as e:
        raise APIError(f"Invalid JSON response: {e}")

# Custom exception classes
class APIError(Exception):
    pass

class InsufficientCreditsError(APIError):
    pass

class ContentPolicyError(APIError):
    pass

class AuthenticationError(APIError):
    pass

class NetworkError(APIError):
    pass

Retry Logic

Implement smart retry logic for transient errors

Retry Strategy

Retry These Errors

  • • 500 Internal Server Error
  • • 502 Bad Gateway
  • • 503 Service Unavailable
  • • Network timeout errors
  • • Temporary server errors

Don't Retry These Errors

  • • 401 Unauthorized
  • • 402 Insufficient Credits
  • • 400 Validation Errors
  • • Content Policy Violations
  • • Invalid API parameters
async function generateWithRetry(prompt, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await generateVideo(prompt);
    } catch (error) {
              // Don&apos;t retry certain errors
      if (error.code === 'INSUFFICIENT_CREDITS' || 
          error.code === 'CONTENT_POLICY_VIOLATION' ||
          error.code === 'INVALID_API_KEY') {
        throw error;
      }
      
      // Retry with exponential backoff
      if (attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      throw error;
    }
  }
}

Troubleshooting Guide

Common issues and their solutions

Quick Troubleshooting

Video Generation Fails

  • 1. Check your API key is valid and active
  • 2. Verify you have sufficient credits
  • 3. Ensure your prompt doesn't violate content policies
  • 4. Try a simpler prompt or different model

Authentication Issues

  • 1. Verify API key format starts with 'veo3_'
  • 2. Check the X-API-Key header is included
  • 3. Ensure no extra spaces or characters in the key
  • 4. Regenerate API key if needed

Rate Limit Errors

  • 1. Implement exponential backoff in retries
  • 2. Check rate limit headers in responses
  • 3. Space out your requests appropriately
  • 4. Consider upgrading for higher limits

Next Steps

Continue learning about the VEO3 API

Code Examples
See error handling in real code examples
Rate Limits
Understand rate limiting and how to avoid 429 errors
Best Practices
Learn best practices for robust API integration