openrouter-common-errors

Openrouter Common Errors

Overview

This skill provides a comprehensive reference for diagnosing and resolving the most frequently encountered OpenRouter API errors.

Prerequisites

• OpenRouter integration
• Basic HTTP status code knowledge

Instructions

1. Identify the error code: Check the HTTP status code and the error.code field in the response body for the specific error type
2. Look up the error: Match the error against the common patterns below — 401 (auth), 402 (credits), 429 (rate limit), 400 (bad request), 5xx (server)
3. Apply the fix: Follow the resolution steps for the specific error; most common errors are configuration issues that can be fixed without code changes
4. Add error handling: Wrap API calls in try/catch blocks that handle each error category differently (retry for 429/5xx, fail fast for 401/400)
5. Prevent recurrence: Add validation middleware that catches common mistakes (missing API key, invalid model ID, malformed messages) before making the API call

Output

• Error diagnosis with root cause identified
• Resolution steps specific to the error encountered
• Preventive validation middleware that catches common mistakes before API calls

Error Handling

Error	Cause	Fix
401 Unauthorized	Invalid, expired, or missing API key	Verify key starts with sk-or-; check it's not revoked at openrouter.ai/keys
402 Payment Required	No credits remaining	Add credits at openrouter.ai/credits; or use a free model like google/gemma-2-9b-it:free
429 Too Many Requests	Rate limit exceeded	Implement exponential backoff; respect Retry-After header; reduce request rate
400 Bad Request	Malformed request body	Validate messages array format; check model ID includes provider prefix
408 Request Timeout	Model took too long to respond	Retry with a faster model; reduce max_tokens; use streaming
502/503 Server Error	Upstream provider outage	Retry with backoff; check status.openrouter.ai; use fallback models

See ${CLAUDE_SKILL_DIR}/references/errors.md for full error reference.

Examples

See ${CLAUDE_SKILL_DIR}/references/examples.md for runnable code samples.

Resources

• OpenRouter Documentation
• OpenRouter Models
• OpenRouter API Reference
• OpenRouter Status