Error Handling

Comprehensive guide to VEO3 API error handling. Learn about error codes, response formats, troubleshooting steps, and best practices for building robust applications.

Comprehensive CoverageActionable SolutionsBest Practices

Error Response Format

All API errors follow a consistent JSON format for easy parsing and handling

Standard Error Response
Every error response includes these fields for consistent error handling
{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human readable error message",
  "details": "Additional error details (optional)",
  "field": "fieldName (for validation errors)",
  "value": "invalidValue (for validation errors)"
}
success:

Always false for errors

error:

Machine-readable error code

message:

Human-readable description

details:

Additional context (optional)

Error Categories

Errors are categorized by HTTP status codes and specific error types

4xx Client Errors
Errors caused by invalid requests or client-side issues
StatusError CodeMessageCommon Cause
400INVALID_PROMPTPrompt is missing or invalidEmpty or malformed prompt
400INVALID_MODELModel ID is not supportedUnknown or misspelled model ID
400VALIDATION_ERRORParameter validation failedInvalid parameter values
400MISSING_IMAGEImage file is required but missingImage-to-video without image file
400INVALID_IMAGE_TYPEImage format not supportedNon-JPEG/PNG image file
400VIDEO_NOT_READYVideo generation not completedTrying to download incomplete video
401UNAUTHORIZEDAPI key missing or invalidMissing or incorrect X-API-Key header
402INSUFFICIENT_CREDITSNot enough credits for generationAccount balance too low
404TASK_NOT_FOUNDVideo generation task not foundInvalid or expired task ID
404NO_VIDEOSNo videos found for completed taskTask completed but videos missing
413FILE_TOO_LARGEImage file exceeds size limitImage file larger than 20MB
429RATE_LIMIT_EXCEEDEDToo many requestsExceeded rate limits
5xx Server Errors
Errors caused by server-side issues or temporary failures
StatusError CodeMessageCommon Cause
500INTERNAL_ERRORInternal server errorUnexpected server error
500GENERATION_FAILEDVideo generation failedGeneration process encountered an error
503SERVICE_UNAVAILABLEService temporarily unavailableServer maintenance or overload
504GATEWAY_TIMEOUTRequest timeoutGeneration took too long to complete

Detailed Error Examples

Common errors with full response examples and solution steps

Insufficient Credits
402INSUFFICIENT_CREDITS
Not enough credits to complete the request

Response Example

{
  "success": false,
  "error": "INSUFFICIENT_CREDITS",
  "message": "Not enough credits to generate video",
  "required": 400,
  "available": 100
}

Solutions

  • Purchase additional credits
  • Use a lower-cost model (VEO 3.0 Fast)
  • Reduce sampleCount parameter
  • Check your credit balance before requests
Invalid Parameters
400VALIDATION_ERROR
One or more parameters failed validation

Response Example

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Duration must be between 5 and 8 seconds",
  "field": "durationSeconds",
  "value": 10
}

Solutions

  • Check parameter ranges and constraints
  • Validate data types (string vs boolean)
  • Ensure required parameters are present
  • Review the parameters documentation
Task Not Found
404TASK_NOT_FOUND
Video generation task could not be found

Response Example

{
  "success": false,
  "error": "TASK_NOT_FOUND",
  "message": "Video generation task not found",
  "taskId": "invalid_task_id"
}

Solutions

  • Verify the task ID is correct
  • Check if the task has expired
  • Ensure you're using the right API key
  • Tasks may expire after 24 hours
Unauthorized Access
401UNAUTHORIZED
Invalid or missing API key

Response Example

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "API key missing or invalid"
}

Solutions

  • Include X-API-Key header in request
  • Verify your API key is correct
  • Check if your API key is active
  • Ensure proper header formatting

Troubleshooting Guide

Step-by-step troubleshooting for common issues

Request Returns 400 Error
  1. 1
    Check all required parameters are present
  2. 2
    Validate parameter data types and ranges
  3. 3
    Ensure JSON is properly formatted
  4. 4
    Review the specific error message for details
Authentication Fails (401)
  1. 1
    Verify X-API-Key header is included
  2. 2
    Check your API key is correct and active
  3. 3
    Ensure no extra spaces in the API key
  4. 4
    Confirm you're using the right environment
File Upload Errors (413/400)
  1. 1
    Check image file size (max 20MB)
  2. 2
    Verify file format (JPEG or PNG only)
  3. 3
    Ensure proper multipart/form-data encoding
  4. 4
    Try with a smaller image file
Rate Limit Exceeded (429)
  1. 1
    Wait for rate limit window to reset
  2. 2
    Implement exponential backoff retry logic
  3. 3
    Reduce request frequency
  4. 4
    Consider upgrading for higher limits
Generation Fails (500)
  1. 1
    Retry the request after a short delay
  2. 2
    Try with different prompt or parameters
  3. 3
    Check service status page
  4. 4
    Contact support if issue persists

Best Practices

Implement robust error handling in your applications

Implement Proper Error Handling
Always check response status and handle errors gracefully
if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.message);
  // Handle specific error types
  switch (error.error) {
    case 'INSUFFICIENT_CREDITS':
      // Redirect to billing page
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // Implement retry with backoff
      break;
    default:
      // Show generic error message
  }
}
Use Exponential Backoff
Retry failed requests with increasing delays
async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}
Validate Before Sending
Check parameters client-side before making API calls
function validateParameters(params) {
  if (!params.prompt || params.prompt.trim().length === 0) {
    throw new Error('Prompt is required');
  }
  if (params.durationSeconds < 5 || params.durationSeconds > 8) {
    throw new Error('Duration must be between 5 and 8 seconds');
  }
  if (params.sampleCount > 2) {
    throw new Error('Maximum 2 videos per request');
  }
}
Monitor API Usage
Track error rates and response times for your application
// Log errors for monitoring
function logError(error, request) {
  console.error({
    timestamp: new Date().toISOString(),
    error: error.error,
    message: error.message,
    endpoint: request.url,
    statusCode: error.status
  });
}

Error Prevention

Proactive measures to reduce errors in your integration

Input Validation
  • Validate parameters before API calls
  • Check file sizes and formats
  • Verify credit balance before generation
  • Sanitize user inputs
Configuration
  • Use environment variables for API keys
  • Set appropriate request timeouts
  • Implement proper logging
  • Monitor API usage patterns

Next Steps

Continue learning about rate limits and see practical examples

Rate Limits
Learn about API rate limits and how to handle them
Examples
See error handling in practice with code examples
Parameters
Review parameter validation rules