Troubleshooting¶
Start from what you see; each section says where to look and what usually fixes it. Vidai explains itself in words on the screen, so the first step is nearly always to open the record it's about.
A call is refused¶
- Find the call in Request logs: paste the request id your program got (the
x-vidai-request-idheader on the answer) into Search or jump to…, or filter by key and Outcome. - Open it. It says what refused it, in words, and links to the rule.
- Match the error code your program got:
| Code your program got | What it means | What to do |
|---|---|---|
invalid_api_key, missing_api_key (401) |
The key is wrong, revoked, expired or missing | Check the key and where it goes in your SDK (Connect your app on Keys) |
api_key_disabled (403) |
The key is turned off (suspended) | Open the key: it says why |
model_not_allowed (403) |
Your team or agent doesn't allow this model | Your account › Models says what you may call |
denied_by_routing_rule (403) |
A routing rule refused it | Open the rule named on the call |
content_guardrail_blocked (403) |
A guardrail blocked the content | The call names what was found; ask for an override if it's a false positive |
rate_limit_exceeded (429) |
The key passed its requests a minute | Slow down, or ask for a higher limit |
ai_traffic_suspended (503) |
Stop AI traffic is on | Wait for an organisation admin to resume it |
fallback_exhausted, routing_target_unavailable (503) |
Every model it could go to failed or was unavailable | See Status and the provider's circuit |
The full list of codes is in the developer reference.
A call is slow, or failing over¶
- Open the call in Request logs: the top line says how long it took. The summary above the list says how long the slowest calls took (95% were faster), and Show details gives a typical call's time; filter by model or provider to see whether the slowness is theirs. The Admin dashboard tracks response time over the period.
- If a fallback answered, the call lists every model a fallback chain tried and why each one failed.
- On System › Status, Providers lists any provider with its circuit open or recovering.
- Trying the next model happens only before anything reaches your program, never mid-stream, and never for uploads, files or batches.
Costs are missing or look wrong¶
| What you see | Why, and what to do |
|---|---|
| Calls waiting for a price | No rate card connected yet: connect it on Settings › Rate card |
| Calls with no price | The model has no price: Set its price from Needs attention, or add a manual price |
| A price looks wrong | Check the model's price and its history on Models; prices that moved a lot may be held for a decision on Money › Prices |
| Totals don't add up across currencies | They're never added: each currency has its own figure |
| Today's cost is low | Cost totals count calls up to about two minutes old; Needs attention says when cost is running behind |
| The rate card is Out of date, Failing or Stuck | See Statuses: rate card; prices on file keep pricing calls meanwhile |
Someone can't sign in¶
| What they see | What to do |
|---|---|
| "That email and password don't match." | Check both; reset the password if needed |
| "Too many sign-in attempts." | Wait the seconds shown, then try again |
| "This link isn't valid any more." | It was used, expired or replaced: ask for a new one |
| They're asked for multi-factor and lost their phone | A recovery code, or an organisation admin resets their multi-factor sign-in from their page in People |
| "You don't have an account here yet." (single sign-on) | Invite them first |
| "Your identity provider didn't confirm your email address." | Ask your IT team, or trust the provider's email addresses in single sign-on settings |
| "Your identity provider isn't answering…" | Try again in a minute; the emergency admin can still sign in with a password |
| "Your organisation has reached the number of people its licence allows." | See Licence |
More: FAQ: signing in.
The gateway or VidaiGuard isn't answering¶
- A notice on every page says The gateway isn't answering: AI calls may be failing. Check System › Status, and ask whoever runs your installation to look at the gateway. The notice goes by itself when it's back.
- VidaiGuard is down Enterprise (set up, but not answering): pattern checks still run. With degrade (the default), calls go through marked partly checked; with strict, calls that needed a VidaiGuard check are refused, and the top bar says how many keys. See VidaiGuard.
- VidaiGuard says Not set up Enterprise: nothing is down. Pattern checks act on their own; to add VidaiGuard, give the gateway its address and choose a model in Settings › VidaiGuard.
- Usage and request logs aren't being recorded: cost and Request logs miss this time until it recovers.
A notice on every page¶
Every notice, what it means and what to do: Notices on every page. The ones that need action now:
- AI traffic is stopped: an organisation admin stopped it on purpose. Resume it once the incident is handled.
- Guardrails are off: no guardrail checks any call. Switch them on in Settings.
- Your licence has expired: renew before the grace period ends.
Something needs attention but I can't fix it¶
The item says who can, when the page that puts it right isn't part of your role. See Needs attention items.