Error Handling Guide

Error Response Structures

Detailed API response structure documentation

Success Response

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 50,
    "candidatesTokenCount": 1500,
    "totalTokenCount": 1550
  }
}

Content Review Rejection

{
  "candidates": [
    {
      "content": { "parts": [] },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "candidatesTokenCount": 0
  }
}

Key: candidatesTokenCount: 0

Generation Rejection

{
  "candidates": [
    {
      "content": { "parts": [] },
      "finishReason": "PROHIBITED_CONTENT"
    }
  ],
  "usageMetadata": {
    "candidatesTokenCount": 10
  }
}

Key: finishReason != "STOP"

Text Response

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "I can't generate images that..."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "candidatesTokenCount": 150
  }
}

Key: Has text, no inlineData

System Error

{
  "candidates": null,
  "error": {
    "code": 500,
    "message": "Internal server error"
  }
}

Key: candidates is null/empty

How is this guide?

Key Code Snippets

Reusable code blocks for error handling

FAQ

Frequently asked questions about error handling

On this page

Success Response

Content Review Rejection

Generation Rejection