| name | openrouter-common-errors |
| description | Diagnose and fix common OpenRouter API errors. Use when encountering error codes, unexpected failures, or debugging API responses. Triggers: 'openrouter error', 'openrouter 401', 'openrouter 429', 'openrouter 402', 'fix openrouter'.
|
| allowed-tools | Read, Write, Edit, Grep, Bash(python3:*), Bash(node:*), Bash(curl:*), Bash(jq:*) |
| version | 1.20.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","openrouter","errors","debugging","troubleshooting"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
OpenRouter Common Errors
Overview
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.
Prerequisites
- An OpenRouter API key (
sk-or-v1-...) exported as OPENROUTER_API_KEY — see the openrouter-install-auth skill for setup
curl and jq to run the Diagnostic Script- Python 3.8+ with the OpenAI SDK for the categorized error handler; Node.js 18+ for the TypeScript typed-error classifier in the references
- The
requests package if you use the Prevention Middleware's pre-flight model check
Instructions
- Identify the failure by HTTP status and
code using the Complete Error Reference table (400/401/402/403/408/429/5xx each map to a specific fix).
- Inspect the body per Error Response Format —
error.code, error.message, and error.metadata.provider_name tell you whether OpenRouter or the upstream provider failed.
- Run the Diagnostic Script: it checks auth via
GET /api/v1/auth/key, computes remaining credits, verifies the model exists in /api/v1/models, and fires a minimal 1-token completion.
- Wrap production calls with
safe_completion() from Python Error Handler — max_retries=3 auto-retries 429 and 5xx, and each exception class raises with its exact remedy.
- Add
validate_before_send() from Prevention Middleware to catch bad model IDs (with suggestions), malformed messages, and context overflows before spending money on a 400.
- If errors persist across retries and providers, check status.openrouter.ai per the Error Handling table.
Complete Error Reference
| HTTP | Error Code | Cause | Fix |
|---|
| 400 | bad_request | Malformed request body | Validate array format; ensure model ID includes provider prefix |
