Token Observe for OpenRouter

OpenRouter’s most distinctive feature is that a caller can steer routing from inside the request body. That is exactly the feature a governance layer cannot forward, because every one of those fields moves a decision outside the boundary where model permissions, the agent’s data policy and the price ceiling are applied.

Six fields are refused, each with a stated reason. models can select vendor-side fallback models that the role check never saw. provider can override provider selection and with it the data-policy enforcement that decides where prompts may go. route delegates routing wholesale. plugins adds vendor-side processing, egress or charges that cannot be authorised or priced. transforms can alter the content that was inspected, after it was inspected. And web_search_options enables vendor-side search egress and charges outside tool governance entirely. The refusal is by presence rather than by value — a null or an empty array is still refused — because silently stripping a field changes the meaning of a request that then succeeds.

The same argument extends to the model string. The retained :online, :nitro, :floor and :exacto suffixes enable vendor-side search or provider selection without making either governable, so they are rejected at the resolved-route boundary as well as at ingress. An alias an operator has mapped to a safe base model remains valid, which is the supported way to keep a convenient short name.

What replaces all of it is route rules. A rule carries a model pattern, a primary target and an ordered fallback chain, all of which are configuration an operator wrote and an audit log recorded, and all of which are subject to the agent’s data policy — a fallback the agent’s policy forbids is filtered out of the chain rather than used. That is the trade this provider page exists to state clearly: you give up in-band routing control, and you get routing decisions that appear in the record and that the price ceiling can bind.

Ordinary OpenAI-compatible extras are deliberately not on the refused list. Fields such as seed, response_format and reasoning_effort do not choose a different provider or model and do not attach an unpriced vendor-side processor, so they arrive as passthrough — governed like any other text, with routing removing any failover target that would drop or reinterpret them.

OpenRouter does its own fallback internally, and that is precisely the behaviour the refused fields turn off. What remains is the gateway’s own chain, decided by failure class rather than by a retry count: timeout, rate_limited and server_error walk down the route rule’s fallbacks, while context_too_long, content_policy, auth and invalid_request do not.

The content-policy case deserves attention on an aggregator specifically. A refusal that reaches you through a broker is still a refusal by whichever safety system produced it, and replaying it at another vendor is a second attempt at the same action with the objection hidden behind a recorded success. Classification is a lossy mapping from heterogeneous vendor error shapes onto seven classes, and a broker adds a layer to that mapping — the published residual is that a provider returning 5xx for what is really a refusal will be failed over, producing exactly the laundering the design prevents elsewhere.

The auth case is simpler and is worth checking first when calls start failing: an authentication failure means the gateway’s OpenRouter key is wrong, revoked or unfunded, and it fails identically wherever that credential is used, so it never fails over. Failing over would mask a broken key behind a more expensive provider until the invoice arrives.

Above the chain, five consecutive failures opens this provider’s circuit breaker for thirty seconds. The breaker survives configuration refreshes, so editing a provider row does not hand a flapping upstream a clean slate, and the metrics gauge reads the same breaker the request path consults rather than a second instance that would show healthy during an outage.