An Engineer's First Day with Rolter

This is the guide to send engineers. It assumes an administrator has made you a member of a project; members mint their own keys and read their own project’s request logs, including the request and response bodies when payload capture is on.

Open the dashboard your administrator gave you and sign in with your company’s single sign-on or the invitation you received. The scope switcher at the top of the rail, under the logo, shows the org, team and project you are working in. Controls that need a role you do not hold are greyed out and say which role they need.

See what you can call

Models → Model Catalog lists the models your project routes. Those public names are what you put in the model field.

Mint your own key

Settings → Account & keys → Generate virtual key: name it after where it will live, pick the project, optionally narrow it to the models the job needs, and set an expiry. The key is shown once — copy it into your secret store. The dialog also gives you the gateway URL and a first request to try, and asks before it closes over a key you have not copied. You can rotate or delete it from the same screen at any time. See Virtual keys.

Make your first call

Rolter speaks both dialects, so the SDK you already use works with only the base URL changed:

from openai import OpenAIclient = OpenAI(base_url="https://gateway.example.com/v1", api_key="<your key>")reply = client.chat.completions.create(    model="gpt-4o",    messages=[{"role": "user", "content": "hello"}],)

from anthropic import Anthropicclient = Anthropic(base_url="https://gateway.example.com", api_key="<your key>")reply = client.messages.create(    model="claude-sonnet-4",    max_tokens=256,    messages=[{"role": "user", "content": "hello"}],)

curl https://gateway.example.com/v1/chat/completions \  -H "Authorization: Bearer <your key>" \  -H "Content-Type: application/json" \  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}'

No key at hand? The Playground mints a 30-minute key for your project on its own.

Point your coding agent at it

Claude Code, Codex, Cursor and other agents can send their own traffic through the gateway, so it is routed, budgeted and logged like everything else. The agent setup page has a prompt that does it for you.

When a call fails#

Walk it in this order — each step narrows where the problem is:

Read the error you got. When Rolter itself refuses a call, the body is OpenAI-style JSON on both dialects, and its type and code name the cause:
- HTTP 401, type authentication_error: the key is missing, wrong or no longer valid.
- HTTP 403, type permission_error, code model_not_allowed, route_not_allowed or provider_not_allowed: the model exists, but your key’s allow-list, or its owner’s access profile, does not reach it or its providers.
- HTTP 403, code required_header_missing: the route requires a header your call did not send; the message names it.
- HTTP 400 (or 403 for a withheld response), code guardrail_blocked or plugin_blocked: a policy on the route refused the content.
- HTTP 404, code model_not_found: there is no route by that name.
- HTTP 402, code insufficient_quota: a budget is spent.
- HTTP 429, code rate_limit_exceeded: a rate limit. Wait the Retry-After seconds.
- HTTP 429, code queue_full or queue_timeout, or HTTP 503, code queue_dropped: the route’s queue is saturated. Back off and retry; these carry no Retry-After.
- HTTP 502, code pii_sanitizer_unavailable: the route’s PII sanitizer could not be reached, so the call was stopped rather than sent unredacted.
- Another 5xx: the route had no target it could send to, or the upstream failed.
Find the request. Every response carries an x-request-id; keep it. GET /api/v1/analytics/invocations?request_id=<x-request-id> with your dashboard session returns the rows logged under that id in projects you are a member of. The id is the client’s own x-request-id when it sent one, so a client that reuses ids gets more than one row back. In the dashboard, open Observability → LLM Logs, paste the x-request-id into the field under the toolbar to open that row, or set the status filter to error and narrow by model. The row shows the target and provider that served it, the error text, retries, latency and cost, plus the request and response bodies when your deployment captures them. A call Rolter refuses before routing it (a 401, 402, 403, 404 or rate-limit 429) leaves no row (#1395), so for those the error body from step 1 is all there is.
Follow it into a trace. Send a W3C traceparent and Rolter joins your distributed trace; look the row’s trace id up in your tracing backend to see where the time went. See Tracing.

Keep an eye on it#

Your usage: Settings → Account & keys shows requests and cost per key over the last week.
Your account: change your password under Settings → Account & keys → Password, and protect the account with a second factor under Two-factor authentication on the same screen.
Your MCP connections: servers that need your consent are under MCP Gateway → Auth Sessions. See MCP OAuth.