こんにちは、ショウです！
最新モデル Gemini 3.1 Pro が登場し、その圧倒的な推論能力やコーディング性能に驚かされる毎日ですが、開発現場では「APIが思うように動かない！」という悲鳴もよく聞こえてきます。
特に「コードは合っているはずなのにエラーが出る」「特定のプロンプトだけ返ってこない」といったトラブルは、AI API特有の仕様が原因であることがほとんどです。
今回は、Google検索でも特に多く相談されている 「Gemini APIの3大エラー」 と、その決定的な対策をまとめました！
1. 【最多】429 Too Many Requests（レート制限）
無料枠（Free Tier）や低ティアのプランを使っていると、必ずぶち当たる壁です。1分あたりのリクエスト数（RPM）やトークン数（TPM）の上限に達すると発生します。
対策：指数関数的バックオフ（Exponential Backoff）
エラーが出た瞬間にすぐ再試行するのではなく、「1秒、2秒、4秒、8秒……」と間隔を倍々に広げてリトライするのが定石です。
Node.jsのライブラリ（p-retryなど）を使うか、以下のような簡易的なループを組み込みましょう。
// 簡易的なリトライ処理のイメージ
for (let i = 0; i < maxRetries; i++) {
try {
const result = await model.generateContent(prompt);
return result;
} catch (error) {
if (error.status === 429) {
await new Promise(res => setTimeout(res, Math.pow(2, i) * 1000));
continue;
}
throw error;
}
}2. 【謎】Candidate was blocked due to SAFETY（安全フィルター）
「エラー文は出ないのに、レスポンスのテキストが空（undefined）になる」という現象の正体です。Gemini 3.1 Proの強力な安全フィルターが、プロンプトや回答案を「不適切」と判定してブロックしています。
対策：SafetySettingsの調整
デフォルト設定はかなり厳しめです。開発中のユースケースに合わせて、安全設定を明示的に指定することで回避できます。
const { HarmCategory, HarmBlockThreshold } = require("@google/generative-ai");
const safetySettings = [
{
category: HarmCategory.HARM_CATEGORY_HARASSMENT,
threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH, // 重大なものだけブロック
},
// 他のカテゴリも同様に設定
];
const model = genAI.getGenerativeModel({ model: "gemini-3.1-pro", safetySettings });3. 【難敵】504 Gateway Timeout（接続時間切れ）
最新の Gemini 3.1 Pro は非常に賢い反面、複雑なタスク（大量のソースコード解析など）を依頼すると、回答生成に数十秒かかることがあります。
サーバー（VercelやNginx等）のタイムアウト設定（通常10〜30秒）をGeminiが超えてしまうと、この504エラーが発生します。
対策：ストリーミング（Streaming）で「沈黙」を破る
回答をすべて待ってから返そうとするからタイムアウトします。generateContentStream を使い、生成されたそばからデータを細切れに送ることで、サーバーに「まだ生きてますよ！」と伝え続けましょう。
const result = await model.generateContentStream(prompt);
for await (const chunk of result.stream) {
const chunkText = chunk.text();
// クライアントへ即座に送信（Server-Sent Eventsなど）
sendToClient(chunkText);
}これだけで、タイムアウトを劇的に減らせるだけでなく、ユーザーの体感待ち時間もほぼゼロになります。
4. まとめ：AIとの「待ち合わせ」をマスターしよう
Gemini API、特に最新の3.1 Proを使いこなすコツは、APIを「ただ呼ぶ」のではなく、**「AIの機嫌（制限や推論時間）を伺いながら呼ぶ」**ことにあります。
- 429: 焦らず間隔を空けてリトライ。
- SAFETY: フィルター設定を正しくコントロール。
- 504: ストリーミングで接続を維持。
これらを実装に組み込むだけで、あなたのアプリの信頼性は一気に「本番クオリティ」になりますよ。
「自分の環境ではこう解決した！」といった事例があれば、ぜひSNSなどで教えてくださいね。
それでは、また！