## Question
How should Gemini API clients distinguish API-key restrictions from model availability?
## Why this matters
Recurring public developer task for AI developer tools.
## Environment / product
AI developer tools
## What needs to be determined
Current researched guidance, applicability, limitations, and primary sources for this question.
Researched guidance is proposed, not an execution report.
Problem details
- Observed symptom
- How should Gemini API clients distinguish API-key restrictions from model availability?
- Context
- Recurring public developer task; researched guidance is proposed, not an execution report.
- Environment
- Unknown · not established
- Symptom signature
- Literal source
- Not supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Researched guidance: How should Gemini API clients distinguish API-key restrictions from model availability?
## Summary
Separate credential and restriction failures from model or endpoint availability by first classifying the response, then checking the requested model and method in the same Gemini API version. API-key failures are signaled by invalid-key or permission errors; model compatibility failures are signaled by absent model metadata, unsupported methods, version mismatch, or NOT_FOUND responses.
## Candidate action
1) Record the exact API version, endpoint, model id, method, HTTP status, error status, and message without logging key material. 2) Treat 400 API_KEY_INVALID and 403 PERMISSION_DENIED as credential, project-access, or key-restriction problems: verify the key is valid, explicitly restricted to the Generative Language API when using a standard key, permitted for the project, and properly authenticated for tuned or otherwise protected resources; do not blindly retry 400/403. Also check whether the key is blocked as leaked. 3) For a 404 NOT_FOUND or a model-related error, call models.list using the intended API surface and inspect the returned model name and supportedGenerationMethods; verify that the requested method is supported and that the model is available on the selected v1 or v1beta endpoint. 4) Check the model lifecycle page for deprecation or shutdown before rotating credentials. 5) Keep 429 RESOURCE_EXHAUSTED (rate or quota), 402 depleted prepay credits, and 400 FAILED_PRECONDITION for unavailable free-tier regions or billing as separate quota, billing, or plan gates; apply the documented retry or remediation behavior rather than labeling them model absence.
## Applicability
- Gemini API clients using API keys with generateContent or another model method, including direct REST calls and SDKs that can select v1 or v1beta.
- Cases where a request fails and the operator must decide whether to repair credentials or select a different model, method, API version, or plan.
## Key findings
- The Gemini API key guide says unrestricted standard keys are rejected, while standard keys with explicit restrictions continue to work; authorization keys are bound to a service account and restricted to the Generative Language API by default. (S1)
- The generateContent error reference maps API-key problems to 400 API_KEY_INVALID examples and 403 PERMISSION_DENIED, and recommends checking key access rather than retrying client errors. (S2, S4)
- The models API lists models available through the Gemini API and exposes supportedGenerationMethods; use that metadata to check model-name and method compatibility before changing credentials. (S3)
- The API-version guide describes v1 as stable and v1beta as actively developing, and notes that Gemini SDKs default to v1beta; a version mismatch can therefore look like model or method unavailability. (S4)
- Google’s model lifecycle pages distinguish deprecation from shutdown: once a model is shut down, its endpoint is no longer available, so lifecycle status must be checked separately from key permissions. (S5)
- An official Google AI Developers Forum diagnostic shows 404 NOT_FOUND wording that explicitly says a model is not found for an API version or is not supported for a method, and directs the caller to ListModels and supported methods. (S6)
- The error reference separates 429 rate limits, 402 depleted prepay credits, and 400 regional free-tier or billing preconditions from permission and resource errors; these are quota, billing, or plan gates rather than proof of model absence. (S2)
## Known limitations
- The official generateContent error table documents 403 permission failures and generic 404 resource failures, but does not guarantee that every model-availability problem uses one unique status or message.
- ListModels is an availability and capability check, not proof that a generation request will succeed; quota, billing, regional, safety, and transient service conditions can still block a call.
- The exact model-related NOT_FOUND wording is corroborated by an official Google AI Developers Forum thread; forum guidance is supplementary to the API reference.
## Obsolete approaches
- Do not rotate API keys solely because a requested model is absent or its method is unsupported; first verify model name, supportedGenerationMethods, API version, and lifecycle status.
- Do not treat every 400, 403, 404, or 429 as interchangeable, and do not repeatedly retry documented client errors.
## Negative results
- The API-key guide does not define model-availability status codes, ListModels behavior, or a complete response-based decision tree; those parts must be combined with the models reference, API-version guidance, and error reference.
- The generateContent error reference does not explicitly name a model-not-found example, so a 404 alone cannot prove that the model is unavailable without checking the model metadata and request version.
## Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
- Documentation and the cited forum diagnostic were read; no Gemini API request was executed and no key, project, model, or quota was independently tested.
## What remains unknown
- Whether a particular client key is restricted, leaked, quota-exhausted, or authorized for a particular model requires inspecting that client’s redacted response and project/key configuration.
- Google does not publish a universal rule in the cited references for how model visibility in models.list changes across every account tier, region, billing state, or preview access program.
- A 404 model response may still need correlation with the selected API version, method, model lifecycle, and account or project entitlements.
## Evidence
- basis: researched_guidance
- executed: false
- independent reproduction: false
## Sources
- [S1] Using Gemini API keys - Google AI for Developers — https://ai.google.dev/gemini-api/docs/generate-content/api-key (official_documentation; accessed 2026-09-21)
- [S2] API errors - generateContent API - Google AI for Developers — https://ai.google.dev/gemini-api/docs/generate-content/api-errors (official_documentation; accessed 2026-09-21)
- [S3] Models - Gemini API - Google AI for Developers — https://ai.google.dev/api/models (official_documentation; accessed 2026-09-21)
- [S4] API versions explained - Gemini API - Google AI for Developers — https://ai.google.dev/gemini-api/docs/api-versions (official_documentation; accessed 2026-09-21)
- [S5] Gemini deprecations - Gemini API - Google AI for Developers — https://ai.google.dev/gemini-api/docs/deprecations (official_documentation; accessed 2026-09-21)
- [S6] Gemini-1.5-flash-001-tuning is not found for API version v1beta - Google AI Developers Forum — https://discuss.ai.google.dev/t/gemini-1-5-flash-001-tuning-is-not-found-for-api-version-v1beta/88739 (community; accessed 2026-09-21)
- Problem id
- 351df585-ca07-4bee-8f27-383bbbda52dc
- Proposed action
- 1) Record the exact API version, endpoint, model id, method, HTTP status, error status, and message without logging key material. 2) Treat 400 API_KEY_INVALID and 403 PERMISSION_DENIED as credential, project-access, or key-restriction problems: verify the key is valid, explicitly restricted to the Generative Language API when using a standard key, permitted for the project, and properly authenticated for tuned or otherwise protected resources; do not blindly retry 400/403. Also check whether the key is blocked as leaked. 3) For a 404 NOT_FOUND or a model-related error, call models.list using the intended API surface and inspect the returned model name and supportedGenerationMethods; verify that the requested method is supported and that the model is available on the selected v1 or v1beta endpoint. 4) Check the model lifecycle page for deprecation or shutdown before rotating credentials. 5) Keep 429 RESOURCE_EXHAUSTED (rate or quota), 402 depleted prepay credits, and 400 FAILED_PRECONDITION for unavailable free-tier regions or billing as separate quota, billing, or plan gates; apply the documented retry or remediation behavior rather than labeling them model absence.
- Applicability
- State
- partial
- Text
- Gemini API clients using API keys with generateContent or another model method, including direct REST calls and SDKs that can select v1 or v1beta. Cases where a request fails and the operator must decide whether to repair credentials or select a different model, method, API version, or plan.
- Limitations
- State
- partial
- Text
- The official generateContent error table documents 403 permission failures and generic 404 resource failures, but does not guarantee that every model-availability problem uses one unique status or message. ListModels is an availability and capability check, not proof that a generation request will succeed; quota, billing, regional, safety, and transient service conditions can still block a call. The exact model-related NOT_FOUND wording is corroborated by an official Google AI Developers Forum thread; forum guidance is supplementary to the API reference.
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
- Pack
- Schema version
- 1
- Candidate action
- 1) Record the exact API version, endpoint, model id, method, HTTP status, error status, and message without logging key material. 2) Treat 400 API_KEY_INVALID and 403 PERMISSION_DENIED as credential, project-access, or key-restriction problems: verify the key is valid, explicitly restricted to the Generative Language API when using a standard key, permitted for the project, and properly authenticated for tuned or otherwise protected resources; do not blindly retry 400/403. Also check whether the key is blocked as leaked. 3) For a 404 NOT_FOUND or a model-related error, call models.list using the intended API surface and inspect the returned model name and supportedGenerationMethods; verify that the requested method is supported and that the model is available on the selected v1 or v1beta endpoint. 4) Check the model lifecycle page for deprecation or shutdown before rotating credentials. 5) Keep 429 RESOURCE_EXHAUSTED (rate or quota), 402 depleted prepay credits, and 400 FAILED_PRECONDITION for unavailable free-tier regions or billing as separate quota, billing, or plan gates; apply the documented retry or remediation behavior rather than labeling them model absence.
- Applicability
- Gemini API clients using API keys with generateContent or another model method, including direct REST calls and SDKs that can select v1 or v1beta.
Cases where a request fails and the operator must decide whether to repair credentials or select a different model, method, API version, or plan. - Limitations
- The official generateContent error table documents 403 permission failures and generic 404 resource failures, but does not guarantee that every model-availability problem uses one unique status or message.
ListModels is an availability and capability check, not proof that a generation request will succeed; quota, billing, regional, safety, and transient service conditions can still block a call.
The exact model-related NOT_FOUND wording is corroborated by an official Google AI Developers Forum thread; forum guidance is supplementary to the API reference. - Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
Documentation and the cited forum diagnostic were read; no Gemini API request was executed and no key, project, model, or quota was independently tested. - What remains unknown
- Whether a particular client key is restricted, leaked, quota-exhausted, or authorized for a particular model requires inspecting that client’s redacted response and project/key configuration.
Google does not publish a universal rule in the cited references for how model visibility in models.list changes across every account tier, region, billing state, or preview access program.
A 404 model response may still need correlation with the selected API version, method, model lifecycle, and account or project entitlements. - Summary
- Separate credential and restriction failures from model or endpoint availability by first classifying the response, then checking the requested model and method in the same Gemini API version. API-key failures are signaled by invalid-key or permission errors; model compatibility failures are signaled by absent model metadata, unsupported methods, version mismatch, or NOT_FOUND responses.
- Obsolete approaches
- Do not rotate API keys solely because a requested model is absent or its method is unsupported; first verify model name, supportedGenerationMethods, API version, and lifecycle status.
Do not treat every 400, 403, 404, or 429 as interchangeable, and do not repeatedly retry documented client errors. - Negative results
- The API-key guide does not define model-availability status codes, ListModels behavior, or a complete response-based decision tree; those parts must be combined with the models reference, API-version guidance, and error reference.
The generateContent error reference does not explicitly name a model-not-found example, so a 404 alone cannot prove that the model is unavailable without checking the model metadata and request version. - Key findings
- Text
- The Gemini API key guide says unrestricted standard keys are rejected, while standard keys with explicit restrictions continue to work; authorization keys are bound to a service account and restricted to the Generative Language API by default.
- Source ids
- S1
- Text
- The generateContent error reference maps API-key problems to 400 API_KEY_INVALID examples and 403 PERMISSION_DENIED, and recommends checking key access rather than retrying client errors.
- Source ids
- S2
S4
- Text
- The models API lists models available through the Gemini API and exposes supportedGenerationMethods; use that metadata to check model-name and method compatibility before changing credentials.
- Source ids
- S3
- Text
- The API-version guide describes v1 as stable and v1beta as actively developing, and notes that Gemini SDKs default to v1beta; a version mismatch can therefore look like model or method unavailability.
- Source ids
- S4
- Text
- Google’s model lifecycle pages distinguish deprecation from shutdown: once a model is shut down, its endpoint is no longer available, so lifecycle status must be checked separately from key permissions.
- Source ids
- S5
- Text
- An official Google AI Developers Forum diagnostic shows 404 NOT_FOUND wording that explicitly says a model is not found for an API version or is not supported for a method, and directs the caller to ListModels and supported methods.
- Source ids
- S6
- Text
- The error reference separates 429 rate limits, 402 depleted prepay credits, and 400 regional free-tier or billing preconditions from permission and resource errors; these are quota, billing, or plan gates rather than proof of model absence.
- Source ids
- S2
- Research sources
- Id
- S1
- Title
- Using Gemini API keys - Google AI for Developers
- Url
- https://ai.google.dev/gemini-api/docs/generate-content/api-key
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S2
- Title
- API errors - generateContent API - Google AI for Developers
- Url
- https://ai.google.dev/gemini-api/docs/generate-content/api-errors
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S3
- Title
- Models - Gemini API - Google AI for Developers
- Url
- https://ai.google.dev/api/models
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S4
- Title
- API versions explained - Gemini API - Google AI for Developers
- Url
- https://ai.google.dev/gemini-api/docs/api-versions
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S5
- Title
- Gemini deprecations - Gemini API - Google AI for Developers
- Url
- https://ai.google.dev/gemini-api/docs/deprecations
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S6
- Title
- Gemini-1.5-flash-001-tuning is not found for API version v1beta - Google AI Developers Forum
- Url
- https://discuss.ai.google.dev/t/gemini-1-5-flash-001-tuning-is-not-found-for-api-version-v1beta/88739
- Source class
- community
- Accessed at
- 2026-09-21
Page 1 · 1 children total
Sources and related records
No source relations recorded.