runbook-openrouter-failure

type/runbook

Runbook — OpenRouter failure during bulk import

Symptoms

  • Bulk import preview shows errors / hangs / returns empty rows.
  • Server logs: 401 (auth), 402 (out of credits), 429 (rate limit), or 5xx from openrouter.ai.
  • Same payload imports cleanly later — likely a transient model availability issue.

Diagnose

# Check the env is set
grep OPENROUTER .env.local

# Test the key directly
curl -s https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | head -c 400

Check the LLM cache — a poisoned cache entry can make a single import fail repeatedly:

  • Cache lives via src/lib/imports/importNormalizeLlmCache.ts. Inspect or clear per its current store.

Fix

  1. 401 / key issue — regenerate key at openrouter.ai, update OPENROUTER_API_KEY in .env.local, restart npm run dev.
  2. 402 / out of credits — top up at openrouter.ai, or switch OPENROUTER_MODEL to the next free-tier entry in the fallback chain (see docs/integrations/ and commit 815bdc7).
  3. 429 / rate-limited — chunking already shrinks per-call size; wait and retry, or lower chunk concurrency in importJsonChunkPlanner.ts.
  4. Model deprecated — OpenRouter rotates free models. Pick a new default, update OPENROUTER_MODEL, document in changelog.
  5. Bad cache entry — clear the LLM cache for the affected input hash, retry.

Prevention

  • Keep the fallback chain in OPENROUTER_MODEL doc current — at least two models deep.
  • Image downscale (importImageDownscale.ts) bounds token cost; don't disable it.

Related

  • [[Projects/personal-finance-notion/changelog/2026-05-03-integrations-bulk-api|Integrations bulk API changelog]]
  • [[Projects/personal-finance-notion/changelog/2026-04-04-import-chunking-image-processing|Import chunking changelog]]