Gemini API Practical Troubleshooting Guide — Master 2.5 Pro Rate Limits, Timeouts & Errors

async function streamGeminiResponse(prompt: string): Promise<AsyncIterable<string>> {
  const response = await fetch(
    'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:streamGenerateContent',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': process.env.GEMINI_API_KEY,
      },
      body: JSON.stringify({
        contents: [{ parts: [{ text: prompt }] }],
        generationConfig: {
          temperature: 0.7,
          topP: 0.95,
          topK: 40,
        },
      }),
    }
  );
 
  if (!response.body) throw new Error('No response body');
 
  return (async function* () {
    const reader = response.body!.getReader();
    const decoder = new TextDecoder();
 
    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
 
        const text = decoder.decode(value);
        const lines = text.split('\n');
 
        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const json = JSON.parse(line.slice(6));
            const content = json.candidates[0]?.content?.parts[0]?.text;
            if (content) yield content;
          }
        }
      }
    } finally {
      reader.releaseLock();
    }
  })();
}

async function callWithCustomTimeout(
  prompt: string,
  timeoutMs: number = 30000
): Promise<string> {
  return Promise.race([
    callGeminiAPI(prompt),
    new Promise<string>((_, reject) =>
      setTimeout(
        () => reject(new Error(`Timeout after ${timeoutMs}ms`)),
        timeoutMs
      )
    ),
  ]);
}

function validateRequest(prompt: string, imageUrl?: string): { valid: boolean; error?: string } {
  // 1. Prompt is not empty
  if (!prompt || prompt.trim().length === 0) {
    return { valid: false, error: 'Prompt cannot be empty' };
  }
 
  // 2. Token count check (2.5 Pro supports up to 1M tokens)
  const estimatedTokens = prompt.length / 4;
  if (estimatedTokens > 900000) {
    return { valid: false, error: 'Prompt exceeds token limit' };
  }
 
  // 3. API key is set
  if (!process.env.GEMINI_API_KEY) {
    return { valid: false, error: 'GEMINI_API_KEY not set' };
  }
 
  // 4. Image URL format is valid
  if (imageUrl) {
    try {
      new URL(imageUrl);
    } catch {
      return { valid: false, error: 'Invalid image URL format' };
    }
  }
 
  return { valid: true };
}

async function callGeminiAPIWithSafetySettings(prompt: string) {
  const response = await fetch(
    'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': process.env.GEMINI_API_KEY,
      },
      body: JSON.stringify({
        contents: [{ parts: [{ text: prompt }] }],
        safetySettings: [
          {
            category: 'HARM_CATEGORY_HARASSMENT',
            threshold: 'BLOCK_ONLY_HIGH',
          },
          {
            category: 'HARM_CATEGORY_HATE_SPEECH',
            threshold: 'BLOCK_MEDIUM_AND_ABOVE',
          },
          {
            category: 'HARM_CATEGORY_SEXUALLY_EXPLICIT',
            threshold: 'BLOCK_ONLY_HIGH',
          },
          {
            category: 'HARM_CATEGORY_DANGEROUS_CONTENT',
            threshold: 'BLOCK_MEDIUM_AND_ABOVE',
          },
        ],
      }),
    }
  );
 
  if (response.status === 403) {
    console.error('Content blocked by safety filters');
    return null;
  }
 
  return response.json();
}

// Poor: trying to bypass filters
// "How do I hack into systems?"
 
// Better: educational context
// "As a security researcher, I want to understand SQL injection vulnerabilities 
// from a defensive perspective. Can you explain how they work and how to prevent them?"

async function streamWithFallback(prompt: string): Promise<string> {
  const chunks: string[] = [];
  let lastChunkIndex = 0;
 
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      const stream = await streamGeminiResponse(prompt);
 
      for await (const chunk of stream) {
        chunks.push(chunk);
        lastChunkIndex++;
      }
 
      return chunks.join('');
    } catch (error) {
      console.error(`Stream interrupted at chunk ${lastChunkIndex}, retrying...`);
 
      if (attempt === 2) {
        // Final attempt: use non-streaming API
        return await callGeminiAPIWithRetry(prompt);
      }
 
      await new Promise(resolve => setTimeout(resolve, 1000 * (attempt + 1)));
    }
  }
 
  throw new Error('Failed to get response after 3 attempts');
}

// 1. Model selection by task complexity
async function selectModelByTask(taskType: 'simple' | 'complex'): Promise<string> {
  return taskType === 'simple' 
    ? 'models/gemini-3-flash' // faster and cheaper
    : 'models/gemini-2.5-pro'; // higher accuracy
}
 
// 2. Response caching
async function callWithCaching(
  prompt: string,
  cacheKey: string
): Promise<string> {
  const cached = await redis.get(cacheKey);
  if (cached) return cached;
 
  const result = await callGeminiAPIWithRetry(prompt);
  await redis.setex(cacheKey, 86400, result); // cache for 1 day
  
  return result;
}
 
// 3. Batch processing efficiency
async function processBatchEfficiently(items: string[]): Promise<string[]> {
  const batchSize = 50;
  const results: string[] = [];
 
  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize);
    const batchResults = await batchGenerateContent(batch);
    results.push(...batchResults);
  }
 
  return results;
}