Foutafhandeling in Gemini API-apps

Fouttypen in de Gemini API

Gemini-fouten vallen in twee categorieën. HTTP-fouten betekenen dat de request de API bereikte maar werd geweigerd of mislukte. Content-fouten betekenen dat de request werd verwerkt, maar dat het resultaat niet bruikbaar is, bijvoorbeeld omdat een safety-filter het antwoord blokkeerde.

Sinds 2025 is de aanbevolen Python-bibliotheek de google-genai SDK (import from google import genai). De oudere google.generativeai SDK is uitgefaseerd en krijgt geen nieuwe modellen of features meer. De voorbeelden hieronder gebruiken daarom de actuele SDK.

HTTP-foutcodes

Let op: authenticatieproblemen geven bij de Gemini API een 403 PERMISSION_DENIED, niet 401. Een 401 is geen standaard Gemini-respons.

Foutafhandeling met de google-genai SDK

De SDK gooit errors.APIError voor fouten van de modelservice. Daaronder vallen errors.ClientError (4xx) en errors.ServerError (5xx). Het exacte HTTP-statusnummer staat in het code-attribuut, zodat je per code een strategie kunt kiezen.

from google import genai
from google.genai import errors
import time
import random
import logging
from enum import Enum

logger = logging.getLogger(__name__)

client = genai.Client(api_key="GEMINI_API_KEY")

class RetryStrategy(Enum):
    NO_RETRY = "no_retry"
    EXPONENTIAL = "exponential"

RETRYABLE_CODES = {429, 500, 503, 504}

def strategy_for_code(code: int) -> RetryStrategy:
    if code in RETRYABLE_CODES:
        return RetryStrategy.EXPONENTIAL
    return RetryStrategy.NO_RETRY

def generate_with_full_error_handling(
    model: str,
    prompt: str,
    max_retries: int = 5,
) -> tuple:
    for attempt in range(max_retries + 1):
        try:
            response = client.models.generate_content(
                model=model,
                contents=prompt,
            )

            feedback = response.prompt_feedback
            if feedback and feedback.block_reason:
                return None, f"Prompt geblokkeerd: {feedback.block_reason.name}"

            candidates = response.candidates
            if not candidates:
                return None, "Geen kandidaatantwoorden gegenereerd"

            candidate = candidates[0]
            if candidate.finish_reason and candidate.finish_reason.name == "SAFETY":
                categorien = [
                    r.category.name for r in (candidate.safety_ratings or [])
                    if r.probability and r.probability.name in ("HIGH", "MEDIUM")
                ]
                return None, f"Antwoord geblokkeerd door safety: {categorien}"

            if candidate.finish_reason and candidate.finish_reason.name == "MAX_TOKENS":
                logger.warning("Antwoord afgekort door MAX_TOKENS")

            return response.text, None

        except errors.APIError as e:
            strategy = strategy_for_code(e.code)

            if strategy == RetryStrategy.NO_RETRY or attempt == max_retries:
                logger.error(f"Fatale fout {e.code}: {e.message}")
                return None, e.message

            wait_time = (2 ** attempt) + random.uniform(0, 1)
            logger.warning(
                f"Fout {e.code}, poging {attempt + 1}/{max_retries}. Wacht {wait_time:.1f}s"
            )
            time.sleep(wait_time)

    return None, "Maximaal aantal pogingen bereikt"

De random.uniform(0, 1) voegt jitter toe. Zonder die ruis proberen meerdere clients precies tegelijk opnieuw, wat de overbelasting in stand houdt.

Safety-fouten specifiek afhandelen

Een blokkade kan op twee plekken ontstaan: in de prompt (prompt_feedback.block_reason) of in het gegenereerde antwoord (finish_reason == SAFETY). Behandel ze apart, want de boodschap aan de gebruiker verschilt.

def handle_safety_block(response) -> dict:
    result = {
        "blocked": False,
        "reason": None,
        "categories": [],
        "text": None,
    }

    feedback = response.prompt_feedback
    if feedback and feedback.block_reason:
        result["blocked"] = True
        result["reason"] = "prompt_blocked"
        result["categories"] = [feedback.block_reason.name]
        return result

    if response.candidates:
        candidate = response.candidates[0]
        if candidate.finish_reason and candidate.finish_reason.name == "SAFETY":
            result["blocked"] = True
            result["reason"] = "output_blocked"
            result["categories"] = [
                r.category.name
                for r in (candidate.safety_ratings or [])
                if r.probability and r.probability.name in ("HIGH", "MEDIUM")
            ]
            return result

        if candidate.content and candidate.content.parts:
            result["text"] = candidate.content.parts[0].text

    return result

Context-limiet fouten

Bij erg lange invoer loop je tegen het context-venster aan of krijg je een 500 of 504 omdat de verwerking te zwaar wordt. Splits de tekst dan in stukken en verwerk die afzonderlijk.

def split_and_process(model: str, long_text: str, chunk_size: int = 50000) -> list:
    words = long_text.split()
    chunks = []
    current = []

    for word in words:
        current.append(word)
        if len(current) >= chunk_size:
            chunks.append(" ".join(current))
            current = []

    if current:
        chunks.append(" ".join(current))

    results = []
    for i, chunk in enumerate(chunks):
        prompt = f"Verwerk deel {i + 1}/{len(chunks)}:
{chunk}"
        text, error = generate_with_full_error_handling(model, prompt)
        if error:
            logger.error(f"Deel {i + 1} mislukt: {error}")
        results.append({"deel": i + 1, "tekst": text, "fout": error})

    return results

Foutlogging voor productie

Log fouten gestructureerd, zodat je ze later kunt filteren op error_code en patronen kunt herkennen (bijvoorbeeld een piek aan 429's die op te lage quota wijst).

import json
import traceback
from datetime import datetime, timezone

def log_api_error(error: Exception, context: dict) -> None:
    log_entry = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "error_type": type(error).__name__,
        "error_code": getattr(error, "code", None),
        "error_message": str(error),
        "context": context,
        "stacktrace": traceback.format_exc(),
    }
    logger.error("gemini_api_error", extra={"data": json.dumps(log_entry)})

Rate limits in de praktijk

De free tier is in december 2025 verlaagd: het aantal verzoeken per minuut ligt nu lager dan voorheen, waardoor apps die eerder werkten ineens 429-fouten konden krijgen. Reken niet op de free-tier limieten voor productie. Limieten gelden over drie assen: verzoeken per minuut (RPM), tokens per minuut (TPM) en verzoeken per dag (RPD), die rond middernacht Pacific Time reset. Schakel facturatie in of vraag een quotaverhoging aan voordat je live gaat, en respecteer altijd de exponentiële backoff uit het voorbeeld hierboven.