Google API errors explained: codes, causes and fixes

Inspect a Gemini error in the context of its API interface, project and model. Distinguish key migration problems, permission failures and generation outcomes before changing an application blindly.

Error format at Google

The current Interactions error reference uses structured code and message fields and documents streaming error events separately. Official documentation.

Identify the API interface before interpreting the error. Preserve the actual structured code, message and request context instead of forcing it into a shape copied from an older example. Record whether the failure occurred during credential setup, request submission, streaming or your own result processing.

Create a redacted fixture that reproduces the condition. For media inputs, replace private files with safe examples that exercise the same format and request shape. Verify that the replacement still fails before sharing it. This gives the project administrator or provider reviewer something actionable without requiring access to customer documents or secret values.

Error code table

Status	Documented code	Investigation	Action
400	`invalid_argument`	Request parameters	Inspect the exact field named in the error.
403	`permission_denied`	Project and key permissions	Repair the applicable access configuration.
404	`model_not_found`	Identifier and availability	Select a documented accessible model.
404	`not_found`	Resource path	Verify the resource reference.

Use the provider’s error reference for the full interface-specific list. Official documentation.

Use the table to choose the next investigation and then inspect the actual response. A missing model, inaccessible project resource and malformed argument need different repairs. Keep the precise code in protected logs while presenting end users with a concise application message suited to their task.

When comparing an error with documentation, match the interface and feature as well as the status. A streaming error event is not the same as a request rejected before a stream starts. Preserve that stage information so a maintainer can inspect the correct part of the application rather than adding a broad exception handler that hides the distinction.

Authentication errors

Inspect authorization-key setup and restrictions. Avoid repeatedly copying an old standard key without checking the current migration guidance.

Check authorization-key migration, restrictions and project permissions before editing the prompt. If the application recently replaced a standard key, verify the new credential in the deployed environment rather than only in a developer terminal. Keep the selected project explicit during this investigation.

For a key-creation problem, have the administrator inspect the documented permissions in that project. Creating duplicate projects can hide the ownership issue while separating the application from its intended billing arrangement. Preserve a secret-free access record so the administrator can identify what the application needs and which configuration was attempted.

Rate and quota errors

Use Gemini project-limit guidance and keep the model and workload class attached to the error report.

Inspect the project’s workload mix and traffic pattern alongside the error. A new media feature or restarted evaluation queue can change capacity pressure without a credential problem. Pause the traffic ramp while collecting representative responses and keep interactive work separate from offline testing.

Give unfinished tasks a clear state and useful lifetime. Do not keep resubmitting after the work can no longer meet its purpose. If account conditions change and access resumes, schedule recovery deliberately rather than releasing an unbounded backlog into the project. Keep the model and modality attached to the diagnostics.

Request validation errors

Reduce the request to the interface’s basic text input. Add media and tool options independently, checking the response after each change.

Return to the simplest request for the selected interface, then add media, tools or conversation state independently. Save each meaningful variation and its outcome. This reveals which change creates the failure without requiring a reviewer to compare an entire application at once.

Inspect input preparation as part of the request. A media file, its declared type and the API field carrying it should be treated as a reproducible unit. If the problem appears only after conversion or resizing in your application, preserve a safe fixture before and after that step so the investigation is not limited to the model call.

Model and context errors

Confirm the identifier and supported capabilities in the model catalog. A model’s documented output type is part of the request contract. Official documentation.

Compare the runtime identifier with the current catalog, including any preview or specialized suffix. Check that the requested output and feature are documented for that candidate. A model selected for general text should not be assumed to implement a separate media-generation workflow.

When reducing a large document request, decide which evidence the task needs before deleting content arbitrarily. Retest whether the answer remains faithful to the source. If changing models repairs acceptance of the request, also rerun the application’s quality and output checks. A successful transport response does not establish that the original task was solved.

Server errors and status

For transient failures, follow the provider’s bounded retry guidance and inspect service evidence if the problem persists. Official documentation.

The Google hub links to the configured official status source.

Use the AI API cost calculator to turn the model and workload you are considering into an estimate.

Record the time window, affected model and application environments for a persistent failure. Compare provider status with your own redacted request evidence. A status notice can support an explanation, while a healthy status view does not invalidate a reproducible problem that affects your request path.

Escalate with the interface, model, safe fixture and actual exception details. State what still works and which bounded recovery was attempted. This helps distinguish a project-access condition, deployment-network issue or feature-specific problem without exposing the credential or asking another person to inspect private application inputs.

Last verified 12 Sep 2026 · Source ↗

Frequently asked questions

Why does the error shape differ from an old example?

Match the example to the API interface; the current reference documents Interactions errors and stream events. Official documentation.

What should I inspect when an old key fails?

The key’s type, restrictions and project access under the current migration guidance. Official documentation.

Should I resend an invalid media request unchanged?

No. Isolate and correct the unsupported field or input first.

What should a useful reproduction include?

The interface, exact model, a non-sensitive input fixture and the actual error body.

Does an open stream prove the generation completed?

No. Handle the stream’s error events and final state. Official documentation.

Sources

Last verified 12 Sep 2026 · Source ↗