To restrict who processes a request, set a provider allowlist and verify both the outgoing request and the processing record. A preference order alone is not evidence that another provider cannot receive the request. If your requirement is “stop when this endpoint is unavailable,” the failure path belongs in your acceptance test.
This guide covers the OpenRouter Chat Completions HTTP interface. Official documentation was checked on 2026-10-03. The example contains placeholders; we did not run paid inference, simulate a provider outage or measure cache performance. For the earlier purchasing decision, see OpenRouter vs direct provider APIs.
How to block a provider on OpenRouter
To block a provider for one request, add "provider": {"ignore": ["REPLACE_WITH_PROVIDER_SLUG"]} to its JSON body. Replace the placeholder with a current provider slug. Use only for an allowlist, ignore for exclusions and order for preference order.
For an account-wide block, use OpenRouter privacy settings. Account exclusions and request exclusions are combined; a request cannot clear the account block. Blocking more providers reduces recovery options. These rules were checked against the official routing documentation on 2026-10-21.
Before changing anything, write down which processor must be excluded and whether other processors remain acceptable. Then inspect the sanitized outgoing request, including retries, and check the processing record described below. Keep the failed attempt visible if no acceptable route remains. This is a proposed verification procedure, not a claim that we ran inference or tested an outage.
Decide which outcomes your product permits
Put this decision into the project specification before choosing settings.
| Business choice | Evidence needed on success | Behavior when unavailable |
|---|---|---|
| Prefer A | Other processors are acceptable and the choice is attributable | Recover within the previously approved scope |
| Accept only A | Every accepted result is attributable to A | Show unavailable, queue work or use manual handling |
| Accept A and B, prefer A | Each result comes from one of the two | Stop when neither is available |
| Accept one exact endpoint | Evidence identifies the endpoint, not merely the company | Do not mark the check passed without sufficient evidence |
When answering every request conflicts with using an approved processor, decide which requirement wins. Retry code should implement that decision rather than invent it during an incident.
The routing settings that matter
The Provider Routing documentation distinguishes order (attempt order) from only (allowlist). With order, allow_fallbacks: false confines attempts to that list. require_parameters: true excludes providers lacking required parameter support.
A base slug can cover several regions or variants; copy the full endpoint slug from the model page when needed. Special service tiers have separate rules. Account and request allowlists intersect; the documented empty-intersection response is 404. None of these settings validates your business result.
A request template for one endpoint
Confirm that the target model currently offers the endpoint, then replace both uppercase placeholders. This template intentionally uses a single model, without an additional model candidate list.
{
"model": "REPLACE_WITH_MODEL_ID",
"messages": [
{ "role": "user", "content": "Return the word ready." }
],
"stream": false,
"provider": {
"only": ["REPLACE_WITH_EXACT_ENDPOINT_SLUG"],
"allow_fallbacks": false,
"require_parameters": true
}
}Send this JSON to https://openrouter.ai/api/v1/chat/completions from your server with Authorization: Bearer <your-key> and Content-Type: application/json. Keep the key out of browser code, screenshots and source control. These are HTTP field names; check how your SDK or third-party client forwards extension parameters.
The short prompt isolates routing setup. Next, substitute a sanitized business example, such as extracting an order number, currency and amount, with explicit expected fields. Receiving ready does not validate structured output, tool calls or streaming.
Inspect the application’s other fallback paths
OpenRouter also supports a top-level models list for fallback between models. A provider setting is not a stop switch for the whole application.
Trace the path from your business function through the SDK and any proxy to OpenRouter. Capture a sanitized outgoing body instead of relying on a settings screenshot:
- Compare initial and retry requests. Check that the
providerobject survives unchanged. - Inspect backup models, alternate base URLs and exception handlers. Determine whether any branch can switch to another route.
- Assign an application task ID and record each attempt. A third-attempt success should not appear to be a first-attempt success.
- Return errors from a local stub to check user messages, queue state and retry limits. A stub verifies application behavior; it does not demonstrate real provider-outage routing.
If two processors are acceptable, run the same business examples against each and evaluate them separately. A shared model family name is not enough to establish equivalent output or failure behavior.
An acceptance worksheet
These are proposed checks, not results obtained by this site. Real requests may incur charges; use your own test account and budget.
| Check | Evidence to retain | Acceptance condition |
|---|---|---|
| Configuration forwarding | Sanitized final JSON, client and configuration versions | Allowlist and required parameters reach the request boundary |
| Normal business input | Request ID, model, processor and field-validation result | Both attribution and output meet requirements |
| No eligible candidate | Conflicting account/request allowlists in an isolated test account, plus the response | Explicit failure; the application does not remove restrictions and retry |
| Application error branch | Local-stub call count, queue and UI state | Stops at the agreed limit without duplicate business actions |
| Release change | Before/after configuration snapshots and the same test case | The release does not widen the approved scope |
Do not change production account preferences to construct a negative case. A misspelled model ID returning an error is not a complete test of provider constraints. If you cannot construct the required test safely, mark it unverified and retain it as a release blocker.
For successful requests, save the generation ID and use the Generation metadata endpoint: GET /api/v1/generation?id=<generation-id>. Review fields such as model, provider_name and total_cost. A company-level provider name alone does not establish the exact endpoint or region; do not record regional verification without sufficient evidence.
A useful record is: task ID / attempt / configuration version / generation ID / actual model / processor / output validation / cost / unresolved checks. Routing logs do not need to contain the original user text.
Diagnose failures without removing the requirement
First check the model/endpoint pairing, then account/request restrictions, then support for your business parameters. An error code is a starting point, not a diagnosis: retain the error description and request context rather than attributing every 404 to one cause.
If direct HTTP behaves as intended but a client does not, compare their sanitized requests. If only the business sample fails, introduce tool or output-format requirements one at a time to locate the difference. Removing all constraints to get a response does not satisfy the original requirement.
Define readiness as attributable processing, acceptable output and controlled failure. Provider pinning does not itself establish cache hits, speed, quality or data residency; each needs its own evidence. You can also consult the OpenRouter directory entry (Chinese) and API cost worksheet (Chinese).