Troubleshooting

Work through the symptom that matches what you're seeing. In almost every case, the Logs tab is the fastest diagnostic — it shows each request's status and the failure pattern (one key? one model? everything?). See Activity & logs.

Requests are blocked

Every request fails with 402 insufficient_credits

Cause: the module is not enabled for this facility, or the prepaid balance is depleted (the Overview tab will show "Your balance is depleted. Inference requests will be blocked until you top up."). For API keys, a facility where Model Router isn't enabled returns 403 "Model Router is not enabled for this facility" instead.

Fix: enable Model Router from the Welcome to Model Router page (see Getting started), then top up under Budgets & Limits → Balance & Top-up. Requests resume within moments of the balance being credited. To prevent recurrence, enable auto top-up. See Budgets & top-ups.

Requests fail with 402 budget_exceeded

Cause: a spend limit was reached. The error message states which window (daily / monthly / lifetime) and — for daily and monthly — exactly when it resets in your facility's timezone. It may be the account-wide limit or a limit on the specific key or connected service (the message says "This key's" / "This agent's" when scoped).

Fix: either wait for the stated reset, raise the limit (Budgets & Limits → Spend Limits, or the key's or service's configuration), or — for the lifetime hard cap — use Reset hard cap. The Spend Limits page shows exactly which limits are at "Limit reached".

Requests fail with 403 content_policy_violation

Cause: the prompt matched a block-mode content filter or the prompt-injection shield.

Fix: review Settings → Guardrails. If one integration legitimately needs different rules, use its Override facility guardrails toggle rather than loosening the facility-wide policy. See Guardrails.

Requests fail with 429

Cause: the key or connected service exceeded its Requests / min or Tokens / min rate limit.

Fix: back off and retry, or raise the rate limits in the key or service configuration (blank = unlimited). See API keys.

A specific model returns errors, others work

Cause: the model may be disabled for your facility, excluded by the key's model restriction, or the provider may be having issues.

Fix: check Settings → Models (is it enabled?), the key's Restrict models list, and Activity → Performance → Reliability & performance by model for the model's error rate over time.

API key problems

401 Unauthorized

Cause: with code invalid_api_key ("Missing or invalid API key"), the Authorization: Bearer … header is missing or malformed. With no code ("Invalid API key"), the key is unknown (mistyped, or an old secret after a rotate) or revoked.

Fix: confirm the header format; check the key's status in Settings → Service Access & API Keys. Re-activate a revoked key, or update your service to the new secret if the key was rotated.

I lost the key secret

The secret is shown only once at creation and cannot be recovered. Use Rotate — a new secret is issued (shown once) and the key keeps its label, limits, and history. Update every service using the key: "You will need to reconfigure any services still using the old key."

The key works but usage shows under the wrong name

Keys are identified by their Label in Activity and Logs. Edit the key and set a meaningful label; give each system its own key rather than sharing one.

Agent problems

An agent shows Offline

Cause: the device is powered off or has no connectivity — this is device connectivity, not a Model Router setting.

Fix: check the device's power and network. Its access configuration is unaffected and works again as soon as it reconnects.

An agent stopped responding to AI requests

Check, in order:

1. Balance — a depleted balance blocks all agents (the agent shows a credits-required state). Top up.
2. Per-service limits — Settings → Service Access & API Keys → Connected Services: does the agent show "Limit reached"? Raise or wait out the limit.
3. Account limits — Budgets & Limits → Spend Limits.
4. Logs — filter by the agent to see the actual error on its requests.

Balance & billing questions

Spend figures look behind

The Available balance and Spent today figures are live. Monthly usage is reconciled against your balance every 15 minutes, so very recent spend can take a few minutes to appear there. The transaction history lists only top-ups and balance adjustments, so usage never shows in it.

Auto top-up didn't run

Check the Balance & Top-up page for a banner: no card on file, card needs authentication, or card declined. Fix the card (Update card / Edit payment details) or top up manually. Auto top-up checks run roughly every 15 minutes, so a just-crossed threshold can take a few minutes to trigger.

A top-up failed

"Additional card authentication is required. Please try again." — retry; your bank may prompt for verification. "Top-up could not be completed." — the charge was declined; check the card or try another amount. No credit is applied unless the charge succeeds.

I was charged but the balance didn't move

Top-ups credit instantly — refresh the page. If the balance still doesn't reflect a successful charge, note the Transaction ID and Payment reference from the transaction's details drawer (or your card statement) and raise a support request.

Logs & analytics questions

A request I just made isn't in the Logs yet

Turn on Live refresh (or click Refresh now). Requests normally appear within moments; under load it can take slightly longer.

Logs show a model I didn't request

If you sent model: "auto", the logs show the model the Auto Router resolved to — open the request's details to see Requested model: auto. This is expected. See Models.

Rows show "No charge"

Failed or empty responses that cost nothing are badged No charge — they're recorded for completeness but didn't consume balance.

My CSV export is smaller than expected

Raw exports are capped at 25,000 rows — narrow the date range or use a summary export. Also note: "Summaries cover whole days, so a sub-day or graph selection is widened to full days."