Error Handling Overview

API Introduction

Model: gemini-3-pro-image-preview
Purpose: AI Image Generation
Feature: Native Google content review

Why Error Handling Matters

The Gemini 3 Pro Image Preview API has multi-layered content review:

1. Content Review Stage - Checks prompts and reference images
2. Generation Stage - Safety filters during generation
3. Output Review - Final content validation

Benefits

For Users

• Clear, actionable error messages
• Understanding of content policies
• Better prompt optimization guidance

For Developers

• Precise error detection
• Comprehensive logging
• Better monitoring

For Product

• Lower rejection rates
• Improved user satisfaction
• Reduced support burden

Main Error Types

1. Content Review Rejection

Indicator: candidatesTokenCount = 0
Trigger: Initial content review
User Message: "Content review failed, please modify"

2. Generation Rejection

Indicator: finishReason != STOP
Trigger: Safety filters during generation
User Message: "Content violates safety policy"

3. Text Response

Indicator: Returns text instead of image
Trigger: Model explains rejection
User Message: Display explanation text

4. System Error

Indicator: candidates null/empty
Trigger: Server errors
User Message: "System error, please retry"

Detection Priority

// Priority order (high to low)
1. candidatesTokenCount === 0  // Content review rejection
2. finishReason !== 'STOP'     // Generation rejection
3. No image data in parts      // Text response
4. candidates null/empty       // System error

Document Structure

1. Core Indicators - Key detection criteria
2. User-Friendly Messages - Message templates
3. Complete Flow - Processing flowchart
4. Code Examples - Implementation code
5. Best Practices - Recommended patterns
6. Key Snippets - Reusable code blocks
7. Error Responses - Response structures
8. FAQ - Common questions
9. Scenarios - Specific error cases

Quick Start

// Basic error detection
function processResponse(data) {
    // 1. Check content review
    if (data.usageMetadata?.candidatesTokenCount === 0) {
        return { error: 'CONTENT_REVIEW_REJECTED' };
    }
    
    // 2. Check generation
    if (data.candidates?.[0]?.finishReason !== 'STOP') {
        return { error: 'GENERATION_REJECTED' };
    }
    
    // 3. Check for image data
    const hasImage = data.candidates[0].content.parts
        .some(p => p.inlineData?.data);
    
    if (hasImage) {
        return { success: true };
    }
    
    return { error: 'NO_IMAGE_DATA' };
}

Next Steps

• Detection: Core Indicators
• Implementation: Code Examples
• UX: User-Friendly Messages