Troubleshooting

Common problems and how to fix them. If a fix needs a server-side change you can't make from the consoles, it's a platform task — see Managing the stack.

A key stopped working

Usually one of three things:

  • Budget hit. If the key has a Max Budget and reached it, it stops working. Check the key's row on the Dashboard — the budget bar turns red at 90%. Raise the budget (or issue a new key).
  • Blocked. The key may have been blocked. Unblock it from the Dashboard.
  • Expired. If it was created with an expiry, it's now disabled. Create a new one.

Every request goes to the same model / routing isn't happening

Routing only kicks in when the request is actually being routed:

  • Is it an auto key? Only keys whose alias starts with auto (or that carry auto_route: true in metadata) route every request. On a non-auto key, an explicit model name passes straight through unchanged.
  • On a non-auto key, ask for the router. Send the model as auto, smart-ai, or default to invoke routing; any other model name is used as-is.

See Virtual keys & auto keys.

I changed a tier but nothing changed

  • Confirm you clicked Save changes in the Control Panel and saw the "Saved — live now" confirmation.
  • Changes apply to the next request — an in-flight or cached test may still show the old model. Send a fresh prompt from the AI Console and read the routing log.
  • Check you edited the right tier. Send a prompt that clearly lands in that tier (e.g. a coding question for COMPLEX) and confirm the tier badge.

Lots of failed or slow requests

  • Free-model rate limits. Free models return 429s under real traffic. If a tier's primary is a :free model with no fallback, add a cheap paid model on the next line so requests fail over instead of failing. See Auto-Switch Control Panel.
  • Check the Dashboard for which key and model the failures are on — the Logs page shows the per-request status and error.

I can't read the routing decision in my browser code

Browsers can't read custom cross-origin response headers, so x-ai-router-tier / x-ai-router-model won't be visible from front-end JavaScript. Read the ai_router object in the response body instead — it carries the tier and the real model. See Using the API.

A provider model returns "not found" or an auth error

  • The provider may be wired but not yet active — its key isn't in place yet. Active vs pending providers are listed in Models & providers. Activating one is a platform task; see Managing the stack.
  • Check the model id is spelled exactly as the provider expects (openrouter/author/model, gemini/gemini-2.5-flash, bedrock/…).

Amazon Bedrock models fail with access denied

Bedrock blocks models until access is granted. In the AWS Bedrock console → Model access, enable each model family you want in the region you're using, and make sure the IAM identity has bedrock:InvokeModel. See Amazon Bedrock.

Spend is higher than expected

  • Open the Dashboard and click into the key with the most spend to see its per-model breakdown. A tier pointed at an expensive model, or a misclassifying setup sending too much to COMPLEX/REASONING, is the usual cause.
  • Review your tier pools in the Control Panel — make sure SIMPLE and MEDIUM lead with genuinely cheap models.
  • The classifier itself is negligible (~$0.00002/request); it's almost never the cost driver.

The AI Console shows a decision my app doesn't get

The Console calls the gateway with model auto through a scoped key — the same path an auto key uses. If your app differs, check that your app's key is an auto key (or that it sends auto), since a non-auto key with an explicit model won't route. See Integrating an application.

Still stuck?

Reach the team at cocolevio.com/contact.