openrouter-known-pitfalls

# 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. ## Pitfall 1: Missing Provider Prefix on Model ID ```python # WRONG: Model ID without provider prefix response = client.chat.completions.create( model="gpt-4o", # ← Will fail with 400 "model not found" messages=[{"role": "user", "content": "Hello"}], ) # RIGHT: Always include provider/model format response = client.chat.completions.create( model="openai/gpt-4o", # ← Correct messages=[{"role": "user", "content": "Hello"}], ) ``` ## Pitfall 2: No max_tokens = Runaway Costs ```python # WRONG: No max_tokens -- model may generate 4000+ tokens response = client.chat.completions.create( model="anthropic/claude-3.5-sonnet", # $15/1M completion tokens messages=[{"role": "user", "content": "Write a story"}], # No max_tokens → could generate $0.06+ per request ) # RIGHT: Always set max_tokens response = client.chat.completions.create( model="anthropic/claude-3.5-sonnet", messages=[{"role": "user", "content": "Write a story"}], max_tokens=500, # ← Caps cost at ~$0.0075 ) ``` ## Pitfall 3: Hardcoded Model IDs Break When Models Are Renamed ```python # WRONG: Hardcoded model ID scattered across codebase # When "claude-3-opus" becomes "claude-3-opus-20240...