Execute diagnose and fix common OpenRouter API errors. Use when troubleshooting failed requests. Trigger with phrases like 'openrouter error', 'openrouter not working', 'openrouter 401', 'openrouter 429', 'fix openrouter'.
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill openrouter-common-errorsLoading…
OpenRouter returns standard HTTP error codes plus OpenRouter-specific error codes in the response body. The most common: 401 (auth), 402 (credits), 429 (rate limit), 400 (bad request), and 5xx (upstream provider errors). Each error includes a code field and a human-readable message. This skill covers every common error, its root cause, and the exact fix.
sk-or-v1-...) exported as OPENROUTER_API_KEY — see the openrouter-install-auth skill for setupcurl and jq to run the Diagnostic Scriptrequests package if you use the Prevention Middleware's pre-flight model checkcode using the Complete Error Reference table (400/401/402/403/408/429/5xx each map to a specific fix).error.code, error.message, and error.metadata.provider_name tell you whether OpenRouter or the upstream provider failed.GET /api/v1/auth/key, computes remaining credits, verifies the model exists in /api/v1/models, and fires a minimal 1-token completion.safe_completion() from Python Error Handler — max_retries=3 auto-retries 429 and 5xx, and each exception class raises with its exact remedy.validate_before_send() from Prevention Middleware to catch bad model IDs (with suggestions), malformed messages, and context overflows before spending money on a 400.| HTTP | Error Code | Cause | Fix |
|---|---|---|---|
| 400 | bad_request | Malformed request body | Validate messages array format; ensure model ID includes provider prefix |
| 400 | invalid_model | Model ID not found | Check model exists: curl -s https://openrouter.ai/api/v1/models | jq '.data[].id' |
| 400 | context_length_exceeded | Prompt + max_tokens > model limit | Reduce prompt size or use a larger-context model |
| 400 | invalid_tool_schema | Tool definition has unsupported types | Use basic JSON Schema types only (string, number, boolean, object, array) |
| 401 | invalid_api_key | Key malformed, revoked, or wrong | Regenerate at openrouter.ai/keys; key must start with sk-or-v1- |
| 401 | missing_api_key | No Authorization header | Add Authorization: Bearer sk-or-v1-... header |
| 402 | insufficient_credits | Credit balance is zero | Top up at openrouter.ai/credits |
| 402 | credit_limit_reached | Per-key credit limit hit | Increase key limit in dashboard or create new key |
| 403 | key_disabled | Key was disabled by admin | Re-enable in dashboard or create new key |
| 408 | request_timeout | Model took too long | Reduce max_tokens; use streaming; try faster model |
| 429 | rate_limit_exceeded | Too many requests per interval | SDK auto-retries; increase max_retries; use multiple keys |
| 502 | provider_error | Upstream provider returned error | Retry with backoff; try different provider via provider.order |
| 503 | model_unavailable | Model temporarily offline | Use fallback models; check status.openrouter.ai |
{
"error": {
"code": 401,
"message": "Invalid API key. Please check your API key and try again.",
"metadata": {
"provider_name": "Anthropic",
"raw": "..."
}
}
}
#!/bin/bash
echo "=== OpenRouter Error Diagnostics ==="
# 1. Test authentication
echo -n "1. Auth: "
AUTH=$(curl -s -o /dev/null -w "%{http_code}" \
https://openrouter.ai/api/v1/auth/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY")
[ "$AUTH" = "200" ] && echo "OK" || echo "FAIL (HTTP $AUTH)"
# 2. Check credit balance
echo -n "2. Credits: "
CREDITS=$(curl -s https://openrouter.ai/api/v1/auth/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY" | \
jq -r '(.data.limit // 0) - .data.usage')
echo "\$$CREDITS remaining"
# 3. Test model availability
echo -n "3. Model: "
MODEL="openai/gpt-4o-mini"
EXISTS=$(curl -s https://openrouter.ai/api/v1/models | \
jq --arg m "$MODEL" '[.data[] | select(.id == $m)] | length')
[ "$EXISTS" -gt 0 ] && echo "$MODEL available" || echo "$MODEL NOT FOUND"
# 4. Test a minimal request
echo -n "4. Request: "
RESP=$(curl -s -w "\n%{http_code}" \
https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":1}')
HTTP=$(echo "$RESP" | tail -1)
[ "$HTTP" = "200" ] && echo "OK" || echo "FAIL (HTTP $HTTP)"
import os
from openai import OpenAI, APIError, AuthenticationError, RateLimitError, BadRequestError, APITimeoutError
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
max_retries=3, # Auto-retry 429 and 5xx
timeout=30.0,
default_headers={"HTTP-Referer": "https://my-app.com", "X-Title": "my-app"},
)
def safe_completion(messages, model="openai/gpt-4o-mini", **kwargs):
"""Completion with categorized error handling."""
try:
return client.chat.completions.create(
model=model, messages=messages, **kwargs
)
except AuthenticationError as e:
# 401: Bad or missing API key
raise SystemExit(f"AUTH ERROR: Check OPENROUTER_API_KEY. {e}")
except BadRequestError as e:
# 400: Bad model ID, invalid params, context too long
if "context_length" in str(e):
raise ValueError(f"Prompt too long for {model}. Trim or use larger-context model.")
raise ValueError(f"Bad request: {e}")
except RateLimitError:
# 429: SDK already retried max_retries times
raise RuntimeError("Rate limited after all retries. Wait or use more API keys.")
except APITimeoutError:
# Timeout: model too slow
raise TimeoutError(f"Model {model} timed out. Try streaming or a faster model.")
except APIError as e:
# 402, 5xx, other
if e.status_code == 402:
raise RuntimeError("Insufficient credits. Top up at openrouter.ai/credits")
raise RuntimeError(f"API error {e.status_code}: {e}")
import requests
def validate_before_send(model: str, messages: list, max_tokens: int = 1024):
"""Pre-flight validation to catch common mistakes before API call."""
errors = []
# Check model exists
models = requests.get("https://openrouter.ai/api/v1/models").json()["data"]
model_ids = {m["id"] for m in models}
if model not in model_ids:
# Try to suggest correct ID
prefix = model.split("/")[0] if "/" in model else ""
suggestions = [m for m in model_ids if prefix and m.startswith(prefix)][:3]
errors.append(f"Model '{model}' not found. Did you mean: {suggestions}")
# Check messages format
if not messages or not isinstance(messages, list):
errors.append("messages must be a non-empty list")
for msg in messages:
if "role" not in msg or "content" not in msg:
errors.append(f"Each message needs 'role' and 'content': {msg}")
# Estimate context usage
total_chars = sum(len(str(m.get("content", ""))) for m in messages)
est_tokens = total_chars // 4
model_info = next((m for m in models if m["id"] == model), None)
if model_info:
ctx_limit = model_info["context_length"]
if est_tokens + max_tokens > ctx_limit:
errors.append(f"Estimated {est_tokens} + {max_tokens} max_tokens > {ctx_limit} context limit")
if errors:
raise ValueError("Pre-flight validation failed:\n" + "\n".join(f" - {e}" for e in errors))
/api/v1/models, and the HTTP status of a minimal live requestsafe_completion() — auth failures exit pointing at the key, 402s point at credit top-up, context overflows raise ValueError naming the model to trim forValueErrors from validate_before_send() listing every problem found (unknown model with suggested IDs, missing role/content fields, estimated-token overflow) before any API call is madeA healthy integration produces this from the Diagnostic Script:
=== OpenRouter Error Diagnostics ===
1. Auth: OK
2. Credits: $46.58 remaining
3. Model: openai/gpt-4o-mini available
4. Request: OK
Any FAIL line maps straight to a row in the Complete Error Reference table — e.g. 1. Auth: FAIL (HTTP 401) means regenerating the key at openrouter.ai/keys. More worked examples: references/examples.md.
| Scenario | SDK Behavior | Your Action |
|---|---|---|
| 429 rate limit | Auto-retries with backoff | Increase max_retries or add keys |
| 5xx server error | Auto-retries with backoff | Increase max_retries; add fallback models |
| 401 auth error | Fails immediately (no retry) | Fix API key and retry |
| 400 bad request | Fails immediately (no retry) | Fix request parameters |
| 402 no credits | Fails immediately (no retry) | Top up credits |
max_retries (default 2, recommend 3-5)
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).