====== API Error Codes Reference ======

Common API errors from OpenAI, Anthropic, and Google with causes and fixes. Quick lookup for debugging.

**Last updated:** March 2026

===== Anthropic Claude API =====

Endpoint: ''%%https://api.anthropic.com/v1/messages%%''

^ HTTP Code ^ Error Type ^ Message ^ Common Cause ^ Fix ^
| 400 | ''invalid_request_error'' | Various | Malformed JSON, missing required fields, invalid model name | Validate request body; check ''model'' string and ''max_tokens'' is set |
| 401 | ''authentication_error'' | "Invalid API Key" | Wrong, expired, or missing API key | Check ''x-api-key'' header; regenerate key in Console |
| 402 | ''billing_error'' | "Billing issue" | Payment method failed or missing | Update payment details in Anthropic Console |
| 403 | ''permission_error'' | "Permission denied" | API key lacks access to the requested resource/model | Check key permissions; upgrade plan if needed |
| 404 | ''not_found_error'' | "Not found" | Invalid endpoint URL or model not available | Verify URL path and model name spelling |
| 413 | ''request_too_large'' | "Request too large" | Request body exceeds 32 MB limit | Reduce message content size; split into multiple requests |
| 429 | ''rate_limit_error'' | "Rate limit exceeded" | Too many requests per minute or tokens per minute | Implement exponential backoff; check usage tier limits |
| 500 | ''api_error'' | "Internal server error" | Anthropic service issue | Retry with backoff; check status.anthropic.com |
| **529** | ''overloaded_error'' | "Overloaded" | API under heavy load across all users | Retry with backoff; this is transient, not account-specific |

**Anthropic-specific notes:**
  * ''max_tokens'' is **required** -- omitting it causes a 400 error
  * 529 is a non-standard HTTP code unique to Anthropic
  * Acceleration limits: rapid traffic ramp-up can trigger 429 even within quota
  * Streaming responses can error after returning HTTP 200 (handle SSE errors)

===== OpenAI API =====

Endpoint: ''%%https://api.openai.com/v1/chat/completions%%''

^ HTTP Code ^ Error Type ^ Message ^ Common Cause ^ Fix ^
| 400 | ''invalid_request_error'' | Various | Malformed request, missing params, unsupported model params | Validate JSON body; check model supports requested features |
| 401 | ''authentication_error'' | "Invalid API key" | Invalid, expired, or revoked key; IP not in allowlist | Verify key; regenerate if needed; check org settings |
| 403 | ''permission_error'' | "Permission denied" | Key lacks model access; country restriction | Check API key permissions; verify account access |
| 404 | ''not_found_error'' | "Model not found" | Typo in model name or model not available to account | Check model name; verify fine-tuned model exists |
| 429 | ''rate_limit_error'' | "Rate limit exceeded" or "Quota exceeded" | Requests/min, tokens/min, or monthly quota exceeded | Backoff + retry; upgrade usage tier; check billing |
| 500 | ''server_error'' | "Internal server error" | OpenAI service issue | Retry with backoff; check status.openai.com |
| 503 | ''service_unavailable'' | "The engine is currently overloaded" | High demand on specific model | Wait and retry; try alternative model |

**OpenAI-specific notes:**
  * Token limit errors return 400, not a separate code -- check ''error.code'' field
  * Content policy violations return 400 with ''error.code: "content_policy_violation"''
  * Fine-tuned model 404s often mean the model is still training or was deleted

===== Google Gemini API =====

Endpoint: ''%%https://generativelanguage.googleapis.com/v1beta/models/...%%''

^ HTTP Code ^ Status ^ Message ^ Common Cause ^ Fix ^
| 400 | ''INVALID_ARGUMENT'' | "Request body is malformed" | Typo, missing field, wrong API version, invalid parameter | Check API reference; verify endpoint version matches features used |
| 400 | ''FAILED_PRECONDITION'' | "Free tier not available" | Region restriction or billing not enabled | Enable billing in Google AI Studio |
| 403 | ''PERMISSION_DENIED'' | "API key lacks permissions" | Wrong key, tuned model access, API not enabled | Verify key; enable Gemini API in Google Cloud Console |
| 404 | ''NOT_FOUND'' | "Model not found" | Invalid model name or model deprecated | Check model name; use ''models.list'' to see available models |
| 429 | ''RESOURCE_EXHAUSTED'' | "Quota exceeded" | Rate limit hit (RPM, TPM, or daily limit) | Backoff + retry; enable billing for higher limits; free tier was reduced Dec 2025 |
| 500 | ''INTERNAL'' | "Internal error" | Google service issue; sometimes caused by very large context | Retry; reduce context size; try Flash instead of Pro |
| 503 | ''UNAVAILABLE'' | "Service temporarily unavailable" | Server overload | Retry with exponential backoff |

**Google-specific notes:**
  * Free tier rate limits were reduced 50-80% in December 2025 -- many 429s are solved by enabling billing
  * ''RESOURCE_EXHAUSTED'' accounts for ~90% of developer-reported errors
  * Safety filter blocks return 200 with empty ''candidates'' -- not an HTTP error
  * Use ''generationConfig.candidateCount: 1'' to avoid unexpected billing

===== Retry Strategy (All Providers) =====

<code python>
import time, random

def retry_with_backoff(func, max_retries=5, base_delay=1.0):
    # Universal retry with exponential backoff + jitter
    retryable_codes = {429, 500, 502, 503, 504, 529}
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            status = getattr(e, 'status_code', getattr(e, 'status', None))
            if status not in retryable_codes or attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            if status == 429:
                retry_after = getattr(e, 'headers', {}).get('retry-after')
                if retry_after:
                    delay = max(delay, float(retry_after))
            time.sleep(delay)
</code>

===== Quick Decision Table =====

^ Scenario ^ Retryable? ^ Action ^
| 429 Rate limit | Yes | Backoff + retry; check Retry-After header |
| 429 Quota exceeded | Depends | Check billing; may need plan upgrade |
| 400 Bad request | No | Fix request body before retrying |
| 401 Auth error | No | Fix API key / credentials |
| 403 Permission | No | Check account access and key permissions |
| 500 Server error | Yes | Retry with backoff (2-3 attempts) |
| 503 Overloaded | Yes | Retry with longer backoff |
| 529 Overloaded (Anthropic) | Yes | Retry with backoff; transient |
| Content policy | No | Modify prompt content |
| Context too long | No | Reduce input tokens or use model with larger context |