OpenRouter Known Pitfalls

Overview

A curated list of real-world mistakes developers make when integrating OpenRouter, each with the specific API behavior that causes the problem and the exact fix. These are not theoretical -- they come from production incidents and support requests.

Prerequisites

• An existing (or in-progress) OpenRouter integration to audit against the 10 pitfalls below
• An OpenRouter API key (sk-or-v1-...) exported as OPENROUTER_API_KEY — see the openrouter-install-auth skill for setup
• Python 3.8+ with the OpenAI SDK (pip install openai) to run the validation snippets (e.g., the startup check against /api/v1/models)
• Grep access to the codebase to hunt hardcoded sk-or-v1- keys and scattered model IDs

Instructions