Gemini API developer errors: Common troubleshooting

When developing with the Gemini API or integrating it via Google Cloud's Vertex AI, you might encounter various errors. Understanding the common categories of these errors and their typical HTTP status codes is crucial for effective troubleshooting. This guide covers key areas including authentication, quotas, request validation, and SDK-specific issues.

Authentication Errors

Authentication issues typically prevent your application from accessing the Gemini API. These often manifest with HTTP 401 Unauthorized or 403 Forbidden status codes.

• 401 Unauthorized: Invalid or Missing Credentials
  • Cause: Your API key is incorrect, expired, or not included in the request. For service accounts, the key file might be misconfigured, or the environment variable (GOOGLE_APPLICATION_CREDENTIALS) might not be set correctly.
  • Solution:
  1. Verify your API key in the Google Cloud Console. Regenerate it if necessary.
  2. Ensure the API key is correctly included in your request headers (e.g., x-goog-api-key) or as a query parameter.
  3. If using a service account, confirm the JSON key file is valid and accessible, and that the environment variable pointing to it is correctly configured.
  4. Check that your project is linked to a billing account, even for free tier usage, as some APIs require it.
• 403 Forbidden: Insufficient Permissions or API Not Enabled
  • Cause: Your authenticated account (API key or service account) lacks the necessary IAM permissions to call the specific Gemini API method, or the Gemini API itself is not enabled for your Google Cloud project.
  • Solution:
  1. In the Google Cloud Console, navigate to IAM & Admin and verify that your service account or API key has roles like "Vertex AI User" or "Vertex AI Service Agent" which grant access to Gemini models.
  2. Go to "APIs & Services > Enabled APIs & Services" and ensure that the "Generative Language API" (for public Gemini API) or "Vertex AI API" (for Vertex AI) is enabled for your project.
  3. Confirm that your API key is restricted to allow calls only from your application's domain or IP address, if applicable.

Quota Exceeded Errors

Quota errors indicate that your project has exceeded the permissible rate or volume of requests. These are typically signaled by an HTTP 429 Too Many Requests status code.

• 429 Resource Exhausted: Quota Exceeded
  • Cause: You've sent too many requests within a specific time frame, or exceeded other limits (e.g., models per minute, daily requests, tokens per minute).
  • Solution:
  1. Implement exponential backoff in your application's retry logic. This automatically retries failed requests after increasing delays.
  2. Review your current quota usage in the Google Cloud Console ("IAM & Admin > Quotas").
  3. If your usage consistently exceeds the default quotas, you can request an increase directly from the Quotas page in the Google Cloud Console. This process can take a few business days.
  4. Optimize your application to reduce the number of API calls or the size of requests if possible.

Request Validation Errors

These errors occur when the structure or content of your API request does not conform to the API's specifications. The most common status code is 400 Bad Request.

• 400 Bad Request: Invalid Argument / Invalid Request Body
  • Cause: Your request payload is malformed (e.g., missing required fields, incorrect data types, invalid enum values) or the prompt content violates safety policies.
  • Solution:
  1. Carefully review the API documentation for the specific endpoint you are calling. Ensure all required fields are present and their values match the expected data types and formats.
  2. Check for common JSON formatting issues (missing commas, curly braces, incorrect quotes).
  3. For text generation, ensure your prompt is clear and does not violate any content safety policies. Test with a very simple prompt to isolate issues.
  4. If using an SDK, ensure you are using the correct method signatures and passing valid parameters according to the SDK's documentation.

SDK-Specific Issues

While the underlying API might be fine, issues can arise from how you're using a client library (SDK).

• Outdated SDK Version:
  • Cause: Older SDK versions might not support new API features or might have bugs that have since been fixed.
  • Solution: Regularly update your SDK to the latest stable version. Check the official documentation for release notes and upgrade guides.
• Incorrect Configuration:
  • Cause: SDKs often require initialization with API keys, project IDs, or specific regions. Misconfiguration can lead to errors.
  • Solution: Double-check the SDK's initialization code. Ensure your API key, project ID, and target region (e.g., us-central1) are correctly specified.
• Dependency Conflicts:
  • Cause: Other libraries in your project might conflict with dependencies used by the Gemini SDK.
  • Solution: Isolate the Gemini API calls in a minimal environment or check your project's dependency tree for conflicts.

Server-Side Errors

Occasionally, errors might originate from the API service itself.

• 500 Internal Server Error: Unexpected Server Issue
  • Cause: A generic server-side error. This usually indicates an issue on Google's end.
  • Solution: Implement retry logic with exponential backoff. If the issue persists, check the Google Cloud Status Dashboard for known outages.
• 503 Service Unavailable: Service Overload or Maintenance
  • Cause: The server is temporarily unable to handle the request due to overload or scheduled maintenance.
  • Solution: Implement retry logic with exponential backoff. Check the Google Cloud Status Dashboard for service announcements.

Related help

• Gemini API Quota Exceeded Error: Fix
• Why Gemini isn't loading or sending prompts?
• Why does Gemini give wrong answers or refuse prompts?