> ## AI Agent Context
> Get the complete documentation index at: https://aistudio.google.com/llms.txt
> Use this file to discover all available pages.
> For the full documentation in a single file, fetch: https://aistudio.google.com/llms-full.txt

# API errors

{% callout type="note" %}
  This version of the page covers the previous **generateContent API**. We recommend using the new [Interactions API](/docs/interactions-overview) for access to all the latest features and models. You can use the toggle on this page to switch to the [Interactions API version of this page](/docs/api-errors).

{% /callout %}

This page provides a reference for backend error codes returned by the `GenerateContent` API, describes the gRPC error response format, and provides troubleshooting steps.

## HTTP error codes  {% id="gc-error-codes" %}

The following table lists common backend error codes, explanations for their causes, and recommended solutions:

| HTTP Code | Status | Description | Example | Solution |
| :--- | :--- | :--- | :--- | :--- |
| 400 | INVALID_ARGUMENT | The request body is malformed. | There is a typo, or a missing required field in your request. | Check the [API reference](/api-reference/generate-content) for request format, examples, and supported versions. Using features from a newer API version with an older endpoint can cause errors. |
| 400 | FAILED_PRECONDITION | Gemini API free tier is not available in your country. Please enable billing on your project in Google AI Studio. | You are making a request in a region where the free tier is not supported, and you have not enabled billing on your project in Google AI Studio. | To use the Gemini API, you will need to setup a paid plan using [Google AI Studio](https://aistudio.google.com/apikey). |
| 402 | RESOURCE_EXHAUSTED | Your Prepay credit balance is depleted. | Your billing account has run out of Prepay credits, so every API key linked to that billing account stops working. | [Add credits](/docs/billing#buy-credits) to your billing account, or turn on [auto-reload](/docs/billing#auto-reload). Don't retry this request: it won't succeed until credits are added. |
| 403 | PERMISSION_DENIED | Your API key lacks the required permissions, or your project is restricted or requires verification or billing changes. | You used a wrong, blocked, or leaked API key, or a tuned model requires [authentication](/docs/model-tuning). Your project needs mobile device verification, or is restricted or ineligible for the free tier. Your billing account may also have an unpaid balance. | Check that your API key is active, complete [project verification](/docs/verification#verify-project), or check billing in [Google AI Studio](https://aistudio.google.com/billing). See [Project restricted or unavailable](/docs/troubleshooting#project-unavailable). |
| 404 | NOT_FOUND | The requested resource wasn't found. | An image, audio, or video file referenced in your request was not found. | Check if all parameters in your request are valid for your API version. |
| 429 | RESOURCE_EXHAUSTED | You've exceeded one of the API's rate limits (RPM, TPM, RPD, spend, etc.). | You are sending too many requests, using too many tokens, or exceeding spend-based limits for your account's billing history and tier. | Verify that you're within the model's [rate limits](/docs/rate-limits). Wait and retry after a short period. Reduce the rate or size of your requests. [Request a rate limit increase](/docs/rate-limits#request-rate-limit-increase) if needed. |
| 499 | CANCELLED | The operation was cancelled, typically by the caller. | The client closed the connection before the API could finish responding. | Check if your client or network infrastructure is prematurely closing the connection (e.g., due to a client-side timeout). |
| 500 | INTERNAL | An unexpected error occurred on Google's side. | Your input context is too long. | Check the [Gemini API status page](https://aistudio.google.com/status) for any ongoing incidents. Reduce your input context or temporarily switch to another model (e.g. from Gemini 2.5 Pro to Gemini 2.5 Flash) and see if it works. Or wait a bit and retry your request. If the issue persists after retrying, please report it using the **Send feedback** button in Google AI Studio. |
| 503 | UNAVAILABLE | The service may be temporarily overloaded or down. | The service is temporarily running out of capacity. | Check the [Gemini API status page](https://aistudio.google.com/status) for any ongoing incidents. Temporarily switch to another model (e.g. from Gemini 2.5 Pro to Gemini 2.5 Flash) and see if it works. Or wait a bit and retry your request. If the issue persists after retrying, please report it using the **Send feedback** button in Google AI Studio. |
| 504 | DEADLINE_EXCEEDED | The service is unable to finish processing within the deadline. | Your prompt (or context) is too large to be processed in time. | Set a larger 'timeout' in your client request to avoid this error. |

## Error response format  {% id="error-schema" %}

When a `GenerateContent` request fails, the API sets the HTTP status code (such as `400 Bad Request`, `403 Forbidden`, or `429 Too Many Requests`) and returns a JSON response body containing gRPC status details:

```json
{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `code` | integer | The HTTP status code. |
| `message` | string | A human-readable description of the error. |
| `status` | string | The gRPC status code in `SCREAMING_CASE`. |
| `details` | array | Additional error context, such as `ErrorInfo` or `LocalizedMessage`. |

## What's next  {% id="whats-next" %}

* [API troubleshooting](/docs/troubleshooting): Resolve common issues and error scenarios.
* [Rate limits](/docs/rate-limits): Learn about request limits and quota handling.