LLM Error Decoder

Cause

Invalid request body — malformed JSON, missing required field, or invalid parameter value.

Fix

Check the error message detail. Common causes: invalid model name, messages array empty, max_tokens too large.

Example response

{"error": {"message": "Invalid model: gpt-5", "type": "invalid_request_error"}}

Cause

API key missing, expired, or invalid.

Fix

Verify OPENAI_API_KEY / ANTHROPIC_API_KEY env var is set. Check key hasn't been rotated. Create new key at platform.openai.com.

Example response

{"error": {"message": "Incorrect API key provided"}}

Cause

API key lacks permission for this model or endpoint.

Fix

Check your account tier. GPT-4 requires paying account. Some models require allowlist access.

Example response

{"error": {"message": "You exceeded your current quota"}}

Cause

Model or endpoint does not exist.

Fix

Check the model name exactly. Model names are case-sensitive. Use /v1/models to list available models.

Example response

{"error": {"message": "The model claude-3-opus does not exist"}}

Cause

Too many requests or token quota exceeded.

Fix

Implement exponential backoff. Check rate limit tier. Use retry-after header. Consider batching or caching.

Example response

{"error": {"message": "Rate limit reached for gpt-4", "type": "requests"}}

Cause

Provider-side error. Transient.

Fix

Retry with exponential backoff (3 attempts). If persistent, check provider status page.

Example response

{"error": {"message": "The server had an error processing your request"}}

Cause

Provider overloaded or under maintenance.

Fix

Check status.openai.com or status.anthropic.com. Implement retry logic. Consider failover to secondary model.

Example response

{"error": {"message": "Service temporarily unavailable"}}

Cause

Total tokens (prompt + completion) exceed model maximum.

Fix

Reduce prompt length, use truncation, or switch to a model with larger context (GPT-4o: 128K).

Example response

{"error": {"type": "context_length_exceeded", "code": "context_length_exceeded"}}

Cause

Anthropic API is temporarily overloaded.

Fix

Retry with exponential backoff. Check status.anthropic.com. Consider using claude-haiku as fallback.

Example response

{"type": "error", "error": {"type": "overloaded_error"}}

Cause

Key format is incorrect (missing sk- prefix, wrong length, etc.)

Fix

OpenAI keys start with sk-. Anthropic keys start with sk-ant-. Don't include Bearer prefix in the key value itself.

Example response

{"error": {"code": "invalid_api_key"}}