Repository Public
1This page provides a reference for all Interactions API error codes, describes the2error response format, and explains how the API delivers errors for different request types.34## Standard API error codes56These general request-level error codes correspond to standard HTTP status codes.7Use the `code` field in your application logic to handle errors programmatically.89| Code | HTTP Status | Description | Recommended action |10|---|---|---|---|11| `invalid_request` | 400 Bad Request | The request payload is malformed or contains invalid parameters. | Check your request syntax and parameters against the [API reference](https://ai.google.dev/api/interactions-api). |12| `failed_precondition` | 400 Bad Request | The request cannot be processed because a prerequisite is not met (for example, disabled billing). | Verify project billing status or account prerequisites. |13| `out_of_range` | 416 Requested Range Not Satisfiable | Request parameter is outside the valid range. | Check parameter values and limits. |14| `parameter_unknown` | 400 Bad Request | The request contains an unknown parameter. | Remove the unrecognized parameter and retry. |15| `authentication` | 401 Unauthorized | The API key is missing, invalid, or expired. | Verify your [API key](https://ai.google.dev/gemini-api/docs/api-key). |16| `permission_denied` | 403 Forbidden | Your API key does not have permission for this resource. | Check your API key permissions and project access. |17| `not_found` | 404 Not Found | The requested resource was not found. | Verify the resource path and parameters. |18| `model_not_found` | 404 Not Found | The specified model was not found. | Verify the model name or fall back to a different model. |19| `already_exists` | 409 Conflict | The entity you attempted to create already exists. | Check if the resource already exists before re-creating. |20| `aborted` | 409 Conflict | The operation was aborted due to a conflict or concurrency check failure. | Retry the request at a higher application level. |21| `rate_limit_exceeded` | 429 Too Many Requests | You have exceeded the per-minute or per-second request or token limit. | Wait and retry with exponential backoff. |22| `quota_exceeded` | 429 Too Many Requests | You have exceeded your daily quota. | Wait until the quota resets or request a quota increase. |23| `too_many_requests` | 429 Too Many Requests | You have made too many requests in a short period of time. | Wait and retry with exponential backoff. |24| `cancelled` | 499 Client Closed Request | The client cancelled the request before it completed. | No action needed. This usually means the client disconnected. |25| `api_error` | 500 Internal Server Error | An unexpected error occurred on the server. | Retry the request. If it persists, contact support. |26| `unimplemented` | 501 Not Implemented | The operation or feature is not implemented or supported. | Check API capabilities or switch to a supported feature. |27| `service_unavailable` | 503 Service Unavailable | The service is temporarily overloaded or down. | Wait and retry with exponential backoff. |28| `deadline_exceeded` | 504 Gateway Timeout | The request didn't finish within the deadline. | Remove or increase client deadline setting to use the server default. |2930> [!NOTE]31> **Note:** Any error code not listed above falls back to the `snake_case` version of the HTTP status.3233## Generation blocked codes3435These error codes indicate that policy, safety, or content restrictions blocked the model's output. When you receive one of these codes, modify your input and retry.3637| Code | Description |38|---|---|39| `safety` | Safety violations (harmful content) blocked the request. |40| `recitation` | Copyright or recitation restrictions blocked the request. |41| `language` | An unsupported language blocked the request. |42| `prohibited_content` | Prohibited content guidelines blocked the request. |43| `spii` | Sensitive Personally Identifiable Information restrictions blocked the request. |44| `blocklist` | Prohibited terms on a blocklist blocked the request. |45| `image_safety` | Safety violations blocked image generation. |46| `image_prohibited_content` | Prohibited content guidelines blocked image generation. |47| `image_recitation` | Copyright or recitation restrictions blocked image generation. |48| `image_other` | Unspecified reasons blocked image generation. |49| `content_blocked` | An unspecified policy reason blocked the request. |5051## Generation error codes5253These error codes indicate a structural issue with the model's generated output (such as a malformed function call or an undeclared tool call).5455| Code | Description |56|---|---|57| `malformed_function_call` | The model produced a function call that could not be parsed. |58| `malformed_tool_call` | The model produced a tool call that could not be parsed. |59| `unexpected_tool_call` | The model called a tool that was not declared in the request. |60| `no_image` | The model was unable to generate an image. |61| `too_many_tool_calls` | The model generated more tool calls than allowed. |62| `missing_thought_signature` | The response is missing a required thought signature. |6364## Error response format6566All errors from the Interactions API return an `error` object containing a `code` and `message`. For example, passing an unsupported tool type returns:6768 {69 "error": {70 "code": "invalid_request",71 "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."72 }73 }7475| Field | Type | Description |76|---|---|---|77| `code` | string | A machine-readable error code in `snake_case`. |78| `message` | string | A human-readable description of what went wrong. |7980## How errors are delivered8182The API delivers errors differently depending on whether you make a standard HTTP request or a streaming (SSE) request.8384### Standard HTTP requests8586For standard (non-streaming) requests, the API sets the HTTP response status code (such as `400 Bad Request`, `401 Unauthorized`, or `429 Too Many Requests`) and returns an `error` object in the JSON response body:8788 {89 "error": {90 "code": "invalid_request",91 "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."92 }93 }9495### Streaming (SSE) requests9697For streaming requests (`stream: true`), the API sends error events over the Server-Sent Events (SSE) stream with `event_type` set to `"error"`. The `error` field contains the same `code` and `message` structure:9899 {100 "event_type": "error",101 "error": {102 "code": "not_found",103 "message": "Failed to get completed interaction: Result not found."104 }105 }106107For the full SSE event schema, see the [Interactions API Reference](https://ai.google.dev/api/interactions-api).108109## What's next110111- [API troubleshooting](https://ai.google.dev/gemini-api/docs/troubleshooting): Resolve common issues and error scenarios.112- [Rate limits](https://ai.google.dev/gemini-api/docs/rate-limits): Learn about request limits and quota handling.