openrouter

OpenRouter

Make model behavior explicit. Preserve the user's quality, cost, privacy, and reliability requirements across every route and retry.

Before changing configuration

1. Inspect the actual outgoing request, SDK version, existing configuration, and user preferences. Redact credentials and content. A setting in a UI or config file does not prove the SDK sends it.
2. Verify exact model IDs and live capabilities through the models API. Inspect the selected model's provider endpoints too. Check input/output modalities, context and output limits, supported parameters, reasoning options, prices, and provider availability for both primary and fallback models.
3. Choose and record an explicit reasoning setting for each reasoning model. Use the user's requested effort. If unspecified, choose a supported value for the task and state the choice; do not silently inherit a provider default or impose one effort on every model. Read reasoning and output before setting these fields.
4. Set an output ceiling, total deadline, bounded retry policy, and cost limits appropriate to the workload. Reasoning uses output tokens too. A model's context window is not its maximum output length.
5. Read the relevant reference below. Consult current official docs for unfamiliar fields; do not invent model IDs, provider slugs, parameter support, or SDK syntax.

Rules that prevent expensive mistakes

• Use the unified reasoning object. reasoning.exclude: true hides reasoning; it does not turn reasoning off or make it free. Mandatory reasoning models cannot be disabled.
• Check every fallback against the same required capabilities and privacy/cost constraints. A single models request shares configuration across candidates. If models need different efforts or budgets, implement bounded application-level attempts with separate configs.
• Separate provider failover from model fallback. provider.order is a preference; only restricts providers; ignore excludes them. Use provider.require_parameters: true when silently dropping requested parameters would break correctness. Recheck endpoint support; this is not a semantic guarantee.
• Match routing to the real goal: provider.sort: "price" for price, "latency" for TTFT, "throughput" for tokens/second. :nitro also permits priority tiers; :floor also permits flex tiers. They can change price or availability beyond plain sorting.
• HTTP 200 is not application success. Check errors, finish reason, expected output type, schema, and task-specific validity. Null text may be a valid tool call. A truncated or unreviewed answer must not become a successful artifact.
• Do not repeat a deterministic failure unchanged. On a confirmed output-limit failure, consider a supported lower effort, smaller task, or compatible fallback within the quality budget. Increasing the cap is one option, not the automatic answer. Preserve fail-closed validation on every attempt.
• Keep keys server-side. Log diagnostic metadata, not prompts, attachments, raw reasoning, or provider errors that may contain private content. Never weaken safety/privacy restrictions just to get a successful response.