Gemini API: Developer errors & HTTP status codes

When working with the Gemini API or Vertex AI for Gemini, developers may encounter various errors. Understanding these errors, often indicated by HTTP status codes or SDK-specific messages, is crucial for effective troubleshooting. This guide covers common developer errors and provides steps to resolve them.

Common HTTP Status Codes

HTTP status codes provide immediate insight into why a request failed. Here are some you might encounter:

• 400 Bad Request: This indicates an issue with your request's format or content.
• Cause: Malformed JSON, incorrect parameter types, missing required fields, or invalid input data (e.g., text too long for the model, invalid safety settings).
• Solution: Review your request body and parameters against the API documentation. Check for typos, correct data types, and ensure all required fields are present. Validate your input data (e.g., prompt length, image format).
• 401 Unauthorized: Your request lacks valid authentication credentials.
• Cause: Missing or incorrect API key, expired OAuth 2.0 token, or invalid service account credentials.
• Solution: Verify your API key is correct and included in the x-goog-api-key header, or that your OAuth 2.0 token is valid and refreshed. Ensure your service account has the necessary permissions.
• 403 Forbidden: Your credentials are valid, but you don't have permission to access the requested resource or perform the action.
• Cause: The API key or service account lacks the required IAM permissions for the specific Gemini API or Vertex AI service. This can also occur if the project isn't enabled for the API.
• Solution: In the Google Cloud console, check that the Gemini API or Vertex AI API is enabled for your project. Verify that the service account or API key's associated identity has the Vertex AI User role (or more specific roles like Vertex AI Service Agent) assigned.
• 429 Too Many Requests (Quota Exceeded): You have sent too many requests in a given time frame.
• Cause: Your project has hit its rate limit or daily quota for API calls.
• Solution: Implement exponential backoff in your code to automatically retry requests after a delay. Check your project's quota usage in the Google Cloud console. Consider requesting a quota increase if your usage consistently exceeds limits.
• 500 Internal Server Error: An unexpected error occurred on the server side.
• Cause: This is a server-side issue. It could be temporary.
• Solution: Wait a short period and retry the request. If the error persists, check the Google Cloud status dashboard for outages.
• 503 Service Unavailable: The server is currently unable to handle the request due to temporary overload or maintenance.
• Cause: Similar to 500, often due to server-side issues or planned maintenance.
• Solution: Implement retries with exponential backoff. Check Google Cloud status for service announcements.

Authentication Issues

Authentication failures are common. Ensure you are using the correct method:

• API Keys: Provide your API key in the x-goog-api-key header. Protect your API keys and restrict their usage.
• OAuth 2.0 / Service Accounts: Generate a short-lived access token and include it in the Authorization: Bearer <TOKEN> header. Ensure your service account has appropriate IAM roles (e.g., Vertex AI User).

Request Validation Errors

Beyond HTTP status 400, specific error messages often detail validation issues:

• INVALID_ARGUMENT: A parameter has an invalid value (e.g., out of range, incorrect format).
• FAILED_PRECONDITION: The system is not in a state required for the operation (e.g., trying to access a model that isn't deployed).
• Solution: The error message usually contains specific details about which argument or precondition failed. Carefully review the API documentation for the exact requirements of the parameters you are sending.

SDK-Specific Issues

When using client libraries (SDKs), errors can sometimes originate from the SDK itself rather than the API. These typically manifest as exceptions in your programming language.

• Outdated SDK: Using an older version of the SDK might lead to compatibility issues with newer API features or bug fixes.
• Solution: Ensure your SDK is updated to the latest version. Refer to the official SDK documentation for installation and update instructions.
• Incorrect Configuration: SDKs often require configuration (e.g., project ID, credentials).
• Solution: Double-check your SDK initialization and configuration settings. Ensure environment variables or configuration files are set correctly.
• Network Issues: The SDK might fail to connect to the API endpoint due to local network problems.
• Solution: Verify your internet connection and any proxy settings. If other network services are also affected, you might be experiencing a broader network issue.

Troubleshooting Steps

1. Check Error Messages: Read the full error response, including any detailed messages, which often pinpoint the exact problem.
2. Consult Documentation: Refer to the official Gemini API or Vertex AI documentation for the specific endpoint and parameters you are using.
3. Verify Credentials: Ensure your API key or service account credentials are correct and have the necessary permissions.
4. Monitor Quotas: Regularly check your project's quota usage in the Google Cloud console to avoid rate limiting.
5. Update SDK: Keep your client libraries updated to benefit from the latest features and bug fixes.
6. Implement Retries: For transient errors (5xx, 429), implement exponential backoff with retries in your application logic.
7. Check Service Status: If you suspect a widespread issue, check the Google Cloud status dashboard.

Related help

• Gemini API Quota Exceeded Error: Fix
• Gemini not loading, responding, or sending prompts?
• Why does Gemini give unexpected answers or refuse prompts?