Skip to main content

FAQ

These short answers route integrators to the canonical documentation page. For buyer and procurement questions, see the Enterprise FAQ.

First Setup​

Which base URL should my client use?​

Use the router deployment URL, not a direct provider URL. Start with Hosted Quickstart and API Compatibility.

Which model value should I send?​

Call /v1/models with your router token and use one returned model-group ID. See Available Models And Access.

Why does /v1/models not show every upstream provider model?​

It returns only model groups allowed for the caller token. See Available Models And Access and Concepts.

How do I choose Docker Compose, binary, Kubernetes, or managed deployment?​

Use the matrix in Installation and the topology guidance in Enterprise Deployment Patterns.

Where do I validate release packages before handoff?​

Use Package Validation And Security Checks.

Authentication And Access​

What does 403 model-not-allowed mean?​

The token is valid but cannot use the requested model group. See Error Reference and Available Models And Access.

What does 403 metrics-forbidden mean?​

The caller token is not authorized for global Prometheus metrics. See Error Reference, Admin Authorization, and Observability.

What should I do when a key is disabled, suspended, expired, or rotated?​

Switch to an active key or ask the operator to rotate access. See Error Reference and User Key Generation.

How are admin reports protected?​

Admin report pages require browser-admin authentication and authorization. See Admin Authentication, Admin Authorization, and Admin Browser Reports.

Routing And Capabilities​

What does 502 no-eligible-target mean?​

The allowed group exists, but no target in that group supports the request shape. See Error Reference, Available Models And Access, and Routing Strategy Decision Tree.

Which routing strategy should I use?​

Start with Routing Strategy Decision Tree. It links to the detailed pages for static, failover, weighted, dynamic score, TypeScript, external policy, and contracts.

How do I route by cost, latency, quality, or request shape?​

Use Dynamic Score Routing unless the policy needs local code or an external service; compare the choices in Routing Strategy Decision Tree.

When should I use TypeScript routing?​

Use it for trusted deployment-local policy code. See TypeScript Routing Policy.

When should I use an external policy service?​

Use it when routing policy should run as its own trusted service. See External Routing Policy Service.

How do model-group contracts relate to routing?​

Contracts enforce capability and quality floors before selection. See Model Group Contracts and Model Group Quality Criteria.

How do I add a provider or model?​

Follow Add A Provider Or Model and keep Model Metadata current.

Client Setup​

How do I configure Codex CLI?​

Use the OpenAI Responses-compatible setup in Codex CLI.

How do I configure Claude Code CLI?​

Use the Anthropic Messages-compatible setup in Claude Code CLI.

Can Codex or Claude Code send images through the same coding group?​

Yes, when the deployment has validated multimodal tool-capable targets in that group. See Codex CLI, Claude Code CLI, and Image Analysis And VLM Routing.

What should I do for 429 traffic-shaped, quota, or rate-limit errors?​

Honor Retry-After, reduce burst size or output caps, and ask an operator to inspect usage. See Error Reference, Request Troubleshooting, and Usage Reporting.

What should I send support when a request fails?​

Send the request ID, status code, client type, model group, and sanitized timing details. Do not send raw tokens, provider keys, prompts, images, or full configs. See Troubleshooting and Security And Trust.