Troubleshooting

Use this section to triage customer-visible failures without exposing secrets or private deployment details. Start from the caller symptom, collect safe evidence, then choose the fix path.

From Troubleshooting, you might be looking for the canonical downstream error contract and error catalog: see Error Responses.

Triage Flow

1. Capture the request ID, HTTP status, router error code, affected model group, client, and UTC time window.
2. Confirm the router is healthy with /readyz, /version, and /v1/models.
3. Use the symptom map below to choose the next page.
4. Open request evidence or usage reports with an authorized admin identity.
5. Apply the smallest fix: caller access, model-group config, quota, provider capacity, target eligibility, credential, or rollback.

First Checks

export ROUTER_BASE_URL="https://<router-host>"
export ROUTER_TOKEN="replace-with-router-token"

curl -fsS "$ROUTER_BASE_URL/readyz"
curl -fsS "$ROUTER_BASE_URL/version"
curl -i -H "Authorization: Bearer $ROUTER_TOKEN" \
  "$ROUTER_BASE_URL/v1/models"

If /readyz fails, check license status, config load errors, database connectivity, and required runtime files before testing individual requests.

If /v1/models does not include the expected model group, inspect caller access policy and model-group configuration. /v1/models is the caller-facing source of truth for allowed groups.

Triage Map

Symptom	Likely area	Next page
One request failed, timed out, or was slow	Request attempts, trace events, upstream provider path, quota, context, or fallback	Request Troubleshooting
/readyz fails with license-* status	License file, expiry, feature gate, volume, instance scope, or clock state	Licensing Troubleshooting
Caller gets 401 or 403	Missing caller token, disabled caller token, model-group access, metrics/report authorization, or admin policy	Request Troubleshooting
Caller gets 429	Router quota, traffic shaping, TPM/RPM, concurrency, license volume/window, or upstream provider limit	Request Troubleshooting
/metrics returns forbidden	Caller is not authorized for metrics admin	Observability
Admin reports unavailable	Admin authentication, authorization policy, usage DB, or report feature license	Admin Browser Reports

Safe Support Packet

When escalating, include:

• router version and build timestamp from /version;
• exact UTC time window;
• request ID values;
• caller-visible error code and HTTP status;
• safe upstream fields when present, such as X-Router-Error-Class, X-Upstream-Status, error.details.error_class, and error.details.upstream_status;
• retry hints when present, such as Retry-After, retry_after_seconds, or error.details.retryable;
• requested model group;
• public token ID when available from reports;
• client name and version when relevant;
• safe license status fields when licensing is involved;
• a redacted summary of the workflow.

Do not include raw router tokens, provider keys, token hashes, raw prompts, raw images, raw tool outputs, full production config, private hostnames, SSH details, private signing material, or full customer-specific license payloads.