LLM API Error Decoder

LLM API errors are terse and provider-specific. This decoder takes the raw message or JSON body and explains, in plain English, what went wrong, the most likely fix, and what to check next — across OpenAI, Anthropic, Gemini and Mistral.

How it works

Paste the error. The tool looks for an HTTP status code and an error type / code field, matches them against a knowledge base of common LLM failure modes, and returns a cause, a recommended action and a category (auth, rate limit, request, server). Matching runs entirely in your browser — nothing is uploaded, so request IDs and prompt fragments stay private.

Common cases

• 401 / invalid_api_key — credentials missing, wrong, or revoked. Rotate the key and check the org/project header.
• 429 / rate_limit_exceeded — too many requests or tokens. Back off exponentially, honour Retry-After, or raise your tier.
• 400 / context_length_exceeded — prompt plus completion exceeds the window. Shorten input, lower max_tokens, or move to a larger model.
• 500 / 503 — transient provider-side issue. Retry with backoff; check the status page.

If the decoder cannot classify your error, lean on the status code: 4xx means your request needs fixing, 5xx means retry the provider.

Error reference by provider

Different providers structure their error responses differently — the decoder recognises each shape automatically:

OpenAI:

{"error": {"message": "...", "type": "invalid_api_key", "code": "invalid_api_key"}}

Anthropic:

{"type": "error", "error": {"type": "authentication_error", "message": "..."}}

Gemini:

{"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}

When to retry — and when not to

Retry with exponential backoff: 429, 500, 502, 503, 504. These are transient failures that resolve on their own. Most provider SDKs handle this automatically if you leave the built-in retry logic enabled.

Do not retry blindly: 400 (malformed request), 401 (bad credentials), 403 (permission denied). Retrying the same bad request wastes quota. Fix the underlying issue first.

Investigate before retrying: 422 — often indicates a content policy rejection, a deprecated model ID, or a structured-output constraint violation. The error message usually identifies which.

Quick fix lookup

Debugging tips that apply across providers

Log the full response body, not just the status code. The HTTP status gives you a rough category; the type, code, or message field inside the body tells you what actually happened. A 400 can be a malformed JSON body, a missing required field, or a content policy violation — the body distinguishes them.

Check provider status pages before deep debugging. A 503 that started 10 minutes ago is very likely an infrastructure incident, not a bug in your code. Check the provider’s status page first; debugging application code during an ongoing outage is wasted time.

Use the Retry-After header when it exists. On a 429, most providers return a Retry-After header (in seconds) or an x-ratelimit-reset header (as a Unix timestamp). Honouring this value is more efficient than fixed exponential backoff and avoids unnecessary additional retries.

Separate API key rotation from quota issues. A 429 with insufficient_quota means your billing plan is exhausted or your spending limit is hit — adding a delay will not help. A 429 with rate_limit_exceeded means you are sending too fast — back off. They share a status code but need different fixes.

Validate structured output requests separately. If you are using JSON mode or function/tool calling and getting 400 errors, extract that part of the request and test it in the provider’s playground first. Schema validation errors are easiest to debug interactively before embedding them in production code.