{
 "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-06-12",
 "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": "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"
  }
 ]
}