Model Availability & Version Errors
Model not found, deprecated, unavailable, or capacity-limited — the fix for each.
19 documented errorsErrors in this category
The model string you passed doesn't match any available Claude model.
Anthropic's capacity temporarily exhausted; retry with backoff or fail over.
You're using a model past its deprecation date; migrate to the current alias.
Your API tier doesn't have access to this specific model (Opus 5 often requires higher tier).
Model version string is malformed or references an internal snapshot.
The model is not available in your API region (AWS Bedrock or Vertex AI cross-region).
The model ID you passed doesn't exist or is not accessible to your org.
Your org doesn't have permission to use this model (usually gating on capacity).
Model is past deprecation date and no longer available.
The specific model is overloaded; smaller variants or Gemini failover often works.
Request exceeds the specific model's context window, even though other models would accept it.
Model exists but isn't supported for the endpoint you called (e.g., chat vs completions).
Model name is invalid; check the models/ prefix and current model catalog.
Model isn't available in your Vertex AI region; use us-central1 or asia-southeast1 fallback.
Per-model quota exhausted while other Gemini models still have quota available.
You're using a preview model that was pulled without notice.
Provider deprecation notice — old model returns errors, migration to new version needed.
Model exists but lacks the capability your request assumes (e.g., vision, tool use, JSON mode).
Same model ID returns different behavior after a silent provider update; retest schemas and prompts.
Related pillar guides
Related blog posts
Frequently asked questions
What's the difference between model_not_found and model_permission_error?
model_not_found means the model ID doesn't exist at all — typo, deprecated model, or wrong provider. model_permission_error means the model exists but your org tier can't access it. Fix for the first: check current model catalog. Fix for the second: contact provider sales or use a lower tier.
How do I know when a model I'm using will be deprecated?
Anthropic and OpenAI publish deprecation dates on their docs pages. Subscribe to their status/blog RSS feeds. Deprecation typically has 6-12 month notice. Never hardcode a version-specific snapshot (e.g., claude-3-5-sonnet-20240620) — use the versioned alias (claude-sonnet-4-6) which auto-updates.
Why does the same model ID sometimes return different behavior?
Providers occasionally push silent updates to versioned aliases. Same model ID, slightly different behavior. Golden dataset tests catch this — run them nightly against production models. If quality regresses, pin to a specific snapshot temporarily and evaluate before migrating.
Should I hardcode model IDs or use aliases?
Aliases in production (auto-migration when providers update); snapshots in tests and evaluations (reproducibility). This split gives you both stability in prod and consistency in your evaluation baseline.
What happens during a model deprecation?
First: provider sends deprecation warning. Second: model still works but returns deprecation headers in response. Third: model returns 404 or deprecation error and stops working. Windows are typically 3-12 months between these stages. Migrate on the warning, not the error.
Can I use different providers' models via one API?
Yes — aggregators like OpenRouter, LiteLLM, and Portkey provide unified interfaces. Tradeoff: another layer of abstraction, another vendor. For simple multi-provider needs, roll your own with the pattern from B6 (Multi-Provider Load Balancer).
What if a model is unavailable in my region?
Options: switch to a region where it's available (Vertex AI supports us-central1, europe-west4, asia-southeast1), use a proxy through a region that has access, or fail over to a different provider whose model is available in your region. See G4 for the fallback patterns.