{
 "note": "Source of truth for the /errors section. Every entry verified against the provider's OWN error documentation on last_verified. Entries map 1:1 to pages at /errors/<slug>. Pages are HAND-WRITTEN editorial (RULE ONE — no template generation); this file powers the hub cards, the validator script, and future automation. Add an entry ONLY with official-doc verification; confidence below 'high' means no page ships.",
 "updated": "2026-08-14",
 "sources_verified": {
  "openai": "https://developers.openai.com/api/docs/guides/error-codes",
  "anthropic": "https://platform.claude.com/docs/en/api/errors",
  "google": "https://ai.google.dev/gemini-api/docs/troubleshooting"
 },
 "errors": [
  {
   "provider": "Google",
   "error_code": "permission_denied",
   "http_status": 403,
   "slug": "gemini-permission-denied",
   "title": "Gemini permission_denied (403): the key can authenticate but cannot use this resource",
   "category": "access-control",
   "severity": "high",
   "severity_note": "high because retrying cannot grant a missing permission and can hide a deployment misconfiguration",
   "short_description": "Gemini accepted the API key but denied access to the requested resource, so retries will not fix the request until project access or key permissions change.",
   "likely_causes": ["The API key belongs to a project without access to the requested resource", "The key's restrictions do not permit the API or calling environment", "The deployment uses a different Google project than the one tested locally", "The requested feature or model is not enabled for that project"],
   "immediate_fix": ["Identify the Google project that owns the production key", "Check that project's API enablement, permissions, and key restrictions", "Compare the resource and model against the access available to that project", "Replace the deployed secret only after the intended project and restrictions are confirmed"],
   "prevention": ["Use separate, labeled keys for local, staging, and production projects", "Record the owning project and allowed APIs in deployment documentation", "Add a pre-deploy smoke test that reports the active project and selected model without exposing secrets"],
   "official_docs": [{"title": "Gemini API errors", "url": "https://ai.google.dev/gemini-api/docs/api-errors"}],
   "related_errors": ["gemini-not-found", "gemini-failed-precondition"],
   "related_models": ["gemini-3-6-flash", "gemini-3-5-flash"],
   "related_deprecations": [],
   "pricing_links": ["/models", "/developers"],
   "last_verified": "2026-08-14",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "OpenAI",
   "error_code": "insufficient_quota",
   "http_status": 429,
   "slug": "openai-insufficient-quota",
   "title": "OpenAI insufficient_quota: what it means and how to fix it",
   "category": "quota-billing",
   "severity": "high",
   "short_description": "Your account has no usable credit or has hit its billing cap — every request fails until billing changes, no matter how slowly you retry.",
   "likely_causes": ["No prepaid credits left on the account", "Monthly budget cap reached", "Free trial credits expired", "Key belongs to an org/project with exhausted quota"],
   "immediate_fix": ["Check Billing in the OpenAI dashboard", "Add credits or raise the budget cap", "Confirm the key's project actually has quota", "Don't retry — backoff can't fix billing"],
   "prevention": ["Usage alerts below the cap", "Per-project budgets", "Route bulk traffic to cheaper models", "Track spend vs the price sheet"],
   "official_docs": [{"title": "OpenAI error codes guide", "url": "https://developers.openai.com/api/docs/guides/error-codes"}],
   "related_errors": ["openai-rate-limit-exceeded", "openai-invalid-api-key"],
   "related_models": ["gpt-5", "gpt-5-mini"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/gpt-5", "/pricing/gpt-5-mini", "/calculator"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "OpenAI",
   "error_code": "rate_limit_exceeded",
   "http_status": 429,
   "slug": "openai-rate-limit-exceeded",
   "title": "OpenAI rate limit errors (429): causes, backoff, and real fixes",
   "category": "rate-limit",
   "severity": "medium",
   "short_description": "Requests or tokens per minute exceeded your tier's ceiling. Temporary by design — limits reset every minute.",
   "likely_causes": ["Bursts of parallel requests", "Tokens-per-minute ceiling hit by long prompts", "Tier limits lower than assumed", "Shared key across services"],
   "immediate_fix": ["Exponential backoff with jitter", "Cap concurrency", "Check the project's published limits", "Respect retry guidance — limits reset every minute"],
   "prevention": ["Queue + smooth bursts", "Cache repeated prompts", "Split batch jobs", "Monitor RPM and TPM separately"],
   "official_docs": [{"title": "OpenAI error codes guide", "url": "https://developers.openai.com/api/docs/guides/error-codes"}],
   "related_errors": ["openai-insufficient-quota", "anthropic-rate-limit-error", "gemini-resource-exhausted"],
   "related_models": ["gpt-5", "gpt-5-mini", "gemini-3-5-flash"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/gpt-5-mini", "/models"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "OpenAI",
   "error_code": "context_length_exceeded",
   "http_status": 400,
   "slug": "openai-context-length-exceeded",
   "title": "OpenAI context_length_exceeded: why prompts overflow and how to fix it",
   "category": "context",
   "severity": "medium",
   "short_description": "Prompt plus requested output exceeds the model's context window. Returned as a 400 invalid_request_error with code context_length_exceeded.",
   "likely_causes": ["Conversation history growing unbounded", "max_tokens set too high on top of a long prompt", "Retrieval stuffing too many chunks", "Wrong model for the document size"],
   "immediate_fix": ["Count tokens before sending", "Trim or summarize history", "Lower max_tokens", "Move the workload to a bigger-window model"],
   "prevention": ["Token budgets per request layer", "Sliding-window history", "Chunk + retrieve instead of stuffing", "Pick context by workload, not by habit"],
   "official_docs": [{"title": "OpenAI error codes guide", "url": "https://developers.openai.com/api/docs/guides/error-codes"}],
   "related_errors": ["anthropic-request-too-large", "gemini-deadline-exceeded"],
   "related_models": ["gpt-5-5", "gpt-5-4", "claude-sonnet-4-6"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/gpt-5-5", "/articles/context-windows-compared"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "OpenAI",
   "error_code": "model_not_found",
   "http_status": 404,
   "slug": "openai-model-not-found",
   "title": "OpenAI model_not_found: the four reasons a model ID 404s in 2026",
   "category": "model-availability",
   "severity": "high",
   "short_description": "The model ID doesn't exist, isn't available to your account, sits on the wrong endpoint — or was retired. In 2026, retirement is the cause to check first.",
   "likely_causes": ["Model retired (the Oct 23, 2026 wave kills 9 IDs)", "Typo or wrong snapshot suffix", "Responses-only model called on chat/completions", "Tier/region lacks access"],
   "immediate_fix": ["Check the ID against the deprecations record", "List available models via the API", "Confirm the right endpoint for the model", "Swap to the official replacement"],
   "prevention": ["Pin IDs in config, not code", "Subscribe to the deprecations feed", "Test replacements before shutdown dates", "Audit usage exports quarterly"],
   "official_docs": [{"title": "OpenAI deprecations", "url": "https://developers.openai.com/api/docs/deprecations"}, {"title": "OpenAI error codes guide", "url": "https://developers.openai.com/api/docs/guides/error-codes"}],
   "related_errors": ["anthropic-not-found-error", "gemini-not-found", "openai-invalid-api-key"],
   "related_models": ["gpt-5", "gpt-5-5"],
   "related_deprecations": ["gpt-4o", "gpt-4-turbo", "o1"],
   "pricing_links": ["/deprecations/openai-october-2026-retirements", "/deprecations/gpt-4o"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "OpenAI",
   "error_code": "invalid_api_key",
   "http_status": 401,
   "slug": "openai-invalid-api-key",
   "title": "OpenAI 401 invalid_api_key / Incorrect API key provided: the checklist",
   "category": "authentication",
   "severity": "high",
   "short_description": "The key is wrong, revoked, malformed in the header, or scoped to the wrong project. Auth fails before anything else runs.",
   "likely_causes": ["Truncated or whitespace-padded key in env vars", "Key revoked or rotated", "Wrong project/organization header", "IP allowlist blocking the caller"],
   "immediate_fix": ["Print the key's first/last 4 chars and length", "Regenerate in the dashboard", "Verify Authorization: Bearer formatting", "Check org membership and IP allowlist"],
   "prevention": ["Secrets manager, never hardcoded", "Per-environment keys", "Rotation runbook", "Startup auth self-check"],
   "official_docs": [{"title": "OpenAI error codes guide", "url": "https://developers.openai.com/api/docs/guides/error-codes"}],
   "related_errors": ["openai-insufficient-quota", "openai-model-not-found"],
   "related_models": ["gpt-5"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/gpt-5"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Anthropic",
   "error_code": "overloaded_error",
   "http_status": 529,
   "slug": "anthropic-overloaded-error",
   "title": "Anthropic overloaded_error (529): what it is and how to ride it out",
   "category": "server-overload",
   "severity": "medium",
   "short_description": "Claude's API is temporarily overloaded across all users — 529 is platform-wide pressure, not your account misbehaving.",
   "likely_causes": ["Platform-wide traffic spikes (launch days)", "Sharp ramp in your own usage triggering acceleration limits (shows as 429)", "Retry storms amplifying the spike"],
   "immediate_fix": ["Backoff with jitter and retry", "Honor the response, don't hammer", "Defer non-urgent jobs to the Batch API", "Check status.anthropic.com"],
   "prevention": ["Ramp traffic gradually", "Circuit breaker around 529 bursts", "Queue with concurrency caps", "A fallback model for degraded mode"],
   "official_docs": [{"title": "Anthropic API errors", "url": "https://platform.claude.com/docs/en/api/errors"}],
   "related_errors": ["anthropic-rate-limit-error", "gemini-resource-exhausted"],
   "related_models": ["claude-sonnet-4-6", "claude-haiku-4-5"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/claude-sonnet-4-6", "/models"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Anthropic",
   "error_code": "rate_limit_error",
   "http_status": 429,
   "slug": "anthropic-rate-limit-error",
   "title": "Anthropic rate_limit_error (429): limits, acceleration, and the fix",
   "category": "rate-limit",
   "severity": "medium",
   "short_description": "Your account hit a rate limit — including Anthropic's acceleration limits, which trigger 429s when usage ramps too sharply even below your ceiling.",
   "likely_causes": ["RPM/TPM ceiling for your tier", "Sharp usage ramp (acceleration limits)", "Parallel agents bursting", "Long prompts eating token budgets"],
   "immediate_fix": ["Exponential backoff with jitter", "Smooth the ramp — consistent traffic patterns", "Cap concurrent requests", "Move bulk jobs to the Batch API"],
   "prevention": ["Gradual ramp-ups before launches", "Request-queue with rate shaping", "Prompt caching to cut tokens", "Monitor 429 rates per key"],
   "official_docs": [{"title": "Anthropic API errors", "url": "https://platform.claude.com/docs/en/api/errors"}],
   "related_errors": ["anthropic-overloaded-error", "openai-rate-limit-exceeded"],
   "related_models": ["claude-haiku-4-5", "claude-sonnet-4-6"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/claude-haiku-4-5", "/calculator"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Anthropic",
   "error_code": "invalid_request_error",
   "http_status": 400,
   "slug": "anthropic-invalid-request-error",
   "title": "Anthropic invalid_request_error (400): the 2026 causes nobody expects",
   "category": "request-format",
   "severity": "medium",
   "short_description": "Malformed request — but in 2026 the usual suspects are new: sampling params on Opus 4.7+, prefilled assistant messages, and modified thinking blocks.",
   "likely_causes": ["temperature/top_p/top_k set on Opus 4.7+ (400 by design)", "Prefilled assistant message on Fable 5 / Opus 4.6+ / Sonnet 4.6", "Edited or filtered thinking blocks sent back", "Plain malformed JSON or missing fields"],
   "immediate_fix": ["Strip sampling params for Opus 4.7+", "Remove assistant prefill; use structured outputs", "Pass thinking blocks back exactly as received", "Validate the body against the Messages schema"],
   "prevention": ["Per-model request builders", "Don't mutate model output before resending", "Contract tests against the API schema", "Read migration guides before swapping IDs"],
   "official_docs": [{"title": "Anthropic API errors (common validation errors)", "url": "https://platform.claude.com/docs/en/api/errors"}, {"title": "Anthropic model deprecations (parameter deprecations)", "url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"}],
   "related_errors": ["anthropic-request-too-large", "anthropic-not-found-error"],
   "related_models": ["claude-opus-4-8", "claude-fable-5", "claude-sonnet-4-6"],
   "related_deprecations": ["claude-opus-4", "claude-opus-4-1"],
   "pricing_links": ["/deprecations/claude-opus-4", "/pricing/claude-opus-4-8"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Anthropic",
   "error_code": "request_too_large",
   "http_status": 413,
   "slug": "anthropic-request-too-large",
   "title": "Anthropic request_too_large (413): the 32 MB wall and how to stay under it",
   "category": "context",
   "severity": "medium",
   "short_description": "The request body exceeded the endpoint's byte cap — 32 MB on Messages. Returned by Cloudflare before Anthropic's servers ever see it.",
   "likely_causes": ["Base64 files inflating the body", "Huge conversation history", "Many images in one request", "Batch built as one giant call"],
   "immediate_fix": ["Use the Files API for big assets (500 MB cap)", "Trim history", "Split the request", "Use the Batch API (256 MB) for bulk"],
   "prevention": ["Measure body size before sending", "Reference files instead of embedding", "Per-request size budget in middleware"],
   "official_docs": [{"title": "Anthropic API errors (request size limits)", "url": "https://platform.claude.com/docs/en/api/errors"}],
   "related_errors": ["openai-context-length-exceeded", "anthropic-invalid-request-error"],
   "related_models": ["claude-sonnet-4-6", "claude-opus-4-8"],
   "related_deprecations": [],
   "pricing_links": ["/articles/context-windows-compared", "/pricing/claude-sonnet-4-6"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Anthropic",
   "error_code": "not_found_error",
   "http_status": 404,
   "slug": "anthropic-not-found-error",
   "title": "Anthropic not_found_error (404): retired Claude models are the 2026 cause",
   "category": "model-availability",
   "severity": "high",
   "short_description": "The requested resource doesn't exist — and since June 15, 2026, the top cause is calling a retired Claude model ID.",
   "likely_causes": ["claude-sonnet-4 / claude-opus-4 retired June 15, 2026", "claude-opus-4-1 retires Aug 5, 2026", "Typo in the model ID or endpoint path", "Resource (file/batch) deleted or wrong ID"],
   "immediate_fix": ["Check the ID against Anthropic's deprecation table", "Swap to the official replacement (Sonnet 4.6 / Opus 4.8)", "Verify the endpoint path", "Use request_id when contacting support"],
   "prevention": ["Model IDs in config with an owner", "Watch the deprecations feed", "60-day notice means calendar reminders work", "Migrate before, not after, shutdown dates"],
   "official_docs": [{"title": "Anthropic API errors", "url": "https://platform.claude.com/docs/en/api/errors"}, {"title": "Anthropic model deprecations", "url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"}],
   "related_errors": ["openai-model-not-found", "gemini-not-found"],
   "related_models": ["claude-sonnet-4-6", "claude-opus-4-8"],
   "related_deprecations": ["claude-sonnet-4", "claude-opus-4", "claude-opus-4-1"],
   "pricing_links": ["/deprecations/claude-sonnet-4", "/deprecations/claude-opus-4"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Google",
   "error_code": "RESOURCE_EXHAUSTED",
   "http_status": 429,
   "slug": "gemini-resource-exhausted",
   "title": "Gemini RESOURCE_EXHAUSTED (429): free-tier limits, quotas, and the fix",
   "category": "rate-limit",
   "severity": "medium",
   "short_description": "You're sending more requests per minute than your tier allows — the signature error of the Gemini free tier.",
   "likely_causes": ["Free-tier RPM ceiling", "Parallel calls on a per-minute quota", "Quota consumed by another app on the same project", "Tier limits lower than the model's marketing"],
   "immediate_fix": ["Backoff and retry after the window resets", "Throttle to your tier's RPM", "Check quotas in AI Studio / Cloud console", "Request a quota increase or enable billing"],
   "prevention": ["Client-side rate shaping", "Separate projects per app", "Budget alerts on paid tiers", "Plan capacity against published limits"],
   "official_docs": [{"title": "Gemini API troubleshooting", "url": "https://ai.google.dev/gemini-api/docs/troubleshooting"}],
   "related_errors": ["gemini-failed-precondition", "openai-rate-limit-exceeded", "anthropic-rate-limit-error"],
   "related_models": ["gemini-3-5-flash", "gemini-3-1-pro"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/gemini-3-5-flash", "/models"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Google",
   "error_code": "INVALID_ARGUMENT",
   "http_status": 400,
   "slug": "gemini-invalid-argument",
   "title": "Gemini INVALID_ARGUMENT (400): malformed requests and version mismatches",
   "category": "request-format",
   "severity": "medium",
   "short_description": "The request body is malformed — a typo, a missing field, or a feature that doesn't exist on the API version you're calling.",
   "likely_causes": ["Typos or missing required fields", "Feature not supported on the endpoint version (v1 vs v1beta)", "Wrong parameter types", "Malformed file references"],
   "immediate_fix": ["Diff the body against the API reference", "Match the feature to the right API version", "Validate JSON types", "Reproduce with a minimal request"],
   "prevention": ["Schema-validate before sending", "Pin API versions explicitly", "Contract tests per endpoint", "Read release notes when switching model lines"],
   "official_docs": [{"title": "Gemini API troubleshooting", "url": "https://ai.google.dev/gemini-api/docs/troubleshooting"}],
   "related_errors": ["gemini-not-found", "anthropic-invalid-request-error"],
   "related_models": ["gemini-3-5-flash", "gemini-3-1-pro"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/gemini-3-1-pro"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Google",
   "error_code": "NOT_FOUND",
   "http_status": 404,
   "slug": "gemini-not-found",
   "title": "Gemini NOT_FOUND (404): missing files — or a model Google already retired",
   "category": "model-availability",
   "severity": "high",
   "severity_note": "high because retired-model 404s break production silently",
   "short_description": "A referenced resource wasn't found: a file you attached, or a model ID from a line Google has shut down.",
   "likely_causes": ["gemini-2.0-flash retired June 1, 2026", "gemini-3-pro-preview dead since March 9, 2026", "2.5 Pro/Flash shut down October 16, 2026", "Missing or expired uploaded-file references"],
   "immediate_fix": ["Check the ID against Google's deprecations page", "Migrate to the listed replacement", "Re-upload expired files", "Verify parameters match your API version"],
   "prevention": ["Track Gemini's earliest-possible shutdown dates", "Config-pinned model IDs", "File-lifetime handling in code", "Test replacements before October 16"],
   "official_docs": [{"title": "Gemini API troubleshooting", "url": "https://ai.google.dev/gemini-api/docs/troubleshooting"}, {"title": "Gemini API deprecations", "url": "https://ai.google.dev/gemini-api/docs/deprecations"}],
   "related_errors": ["openai-model-not-found", "anthropic-not-found-error"],
   "related_models": ["gemini-3-5-flash", "gemini-3-1-pro"],
   "related_deprecations": ["gemini-2-5-pro", "gemini-2-5-flash", "gemini-2-0-flash"],
   "pricing_links": ["/deprecations/gemini-2-5-pro", "/pricing/gemini-3-5-flash"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Google",
   "error_code": "DEADLINE_EXCEEDED",
   "http_status": 504,
   "slug": "gemini-deadline-exceeded",
   "title": "Gemini DEADLINE_EXCEEDED (504): when big prompts outrun the clock",
   "category": "server-overload",
   "severity": "low",
   "short_description": "The service couldn't finish before the deadline — usually a huge prompt or context that needs more processing time than your client allows.",
   "likely_causes": ["Very large prompt/context", "Client timeout set too low", "Long generations without streaming", "Oversized inputs also surfacing as 500 INTERNAL"],
   "immediate_fix": ["Raise the client timeout", "Stream instead of waiting for full output", "Cut the context down", "Retry once after trimming"],
   "prevention": ["Streaming as default for long outputs", "Context budgets per request", "Chunk large documents", "Timeouts sized to the workload"],
   "official_docs": [{"title": "Gemini API troubleshooting", "url": "https://ai.google.dev/gemini-api/docs/troubleshooting"}],
   "related_errors": ["gemini-resource-exhausted", "openai-context-length-exceeded"],
   "related_models": ["gemini-3-5-flash", "gemini-3-1-pro"],
   "related_deprecations": [],
   "pricing_links": ["/articles/context-windows-compared", "/pricing/gemini-3-5-flash"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  },
  {
   "provider": "Google",
   "error_code": "FAILED_PRECONDITION",
   "http_status": 400,
   "slug": "gemini-failed-precondition",
   "title": "Gemini FAILED_PRECONDITION (400): the free-tier region and billing wall",
   "category": "quota-billing",
   "severity": "high",
   "short_description": "The Gemini free tier isn't available in your region without billing — the API refuses before processing anything.",
   "likely_causes": ["Country not covered by the free tier", "No billing account linked", "Server region differs from where you tested (common with VPS/cloud deploys)"],
   "immediate_fix": ["Enable billing in Google AI Studio", "Confirm the project's billing link", "Check where your server actually runs"],
   "prevention": ["Enable billing before deploying abroad", "Treat region as part of deploy config", "Budget alerts once billed"],
   "official_docs": [{"title": "Gemini API troubleshooting", "url": "https://ai.google.dev/gemini-api/docs/troubleshooting"}],
   "related_errors": ["gemini-resource-exhausted", "gemini-invalid-argument"],
   "related_models": ["gemini-3-5-flash"],
   "related_deprecations": [],
   "pricing_links": ["/pricing/gemini-3-5-flash", "/articles/best-free-ai-no-subscription"],
   "last_verified": "2026-06-12",
   "status": "active",
   "confidence": "high"
  }
 ]
}