Skip to main content
Start with the failing boundary: authentication to Relay, model decision, provider execution, telemetry export, or report generation.

Relay rejects the key

Confirm the value begins with ox_, belongs to the intended project, is not disabled or revoked, and has not expired. The full key is shown only at creation; a displayed prefix is not usable authentication.
Add a provider credential to the project, enable it, and run verification. Check the provider-specific error and any custom API base URL. A catalog model can exist without being callable for this project.
Callable and routable are separate properties. Automatic and custom routers require routing-engine support. Use a routable candidate or request the callable model directly.
Confirm the request uses oximy/auto, the routing mode is automatic, at least one candidate is callable and routable, and a fallback is configured. Inspect the Traffic routing reason and upstream error.
Route-only returns a decision but does not execute the provider call. Your application owns the decision-service timeout, provider retry, and final application fallback.
Check the ingest URL, /v1/traces path for standard OTLP/HTTP, Authorization: Bearer ox_... header, exporter protocol, and project key. Generate one identifiable trace and first verify arrival before debugging missing attributes.
Inspect the raw trace spans and instrumentation attributes. Model, token, cost, latency, task, and decision fields can only be displayed when the gateway or telemetry supplies them.
Current grouping infers continuity from message prefixes over a bounded recent window. Treat it as a navigation aid and inspect the ordered traffic rows when exact session boundaries matter.
Verify a callable provider, candidate model, enabled setting, sample availability, and remaining budget. Shadow and evaluations execute additional calls and can stop at their configured cap.
Historical requests may not match the current candidate capabilities or contain enough decision context. Narrow the traffic cohort, review signal filters, and inspect representative unroutable rows.
Check plan entitlements, payment requirements, key-group policy, and project state. Durable key creation can require Relay billing coverage or a payment method.

​
Collect before escalating

Include:
  • project ID and Relay key prefix, never the full secret
  • UTC timestamp and request or decision identifier
  • integration path: gateway, existing gateway, OTEL, or route-only
  • requested and resolved model
  • provider verification status
  • HTTP status and sanitized error
  • relevant limit and budget state
Do not paste provider credentials, full Relay keys, prompts containing sensitive data, or unsanitized provider responses into a support ticket.