aivokey

Troubleshooting

Fixes for the most common problems.

Find your symptom below. Most problems are one of the first four.

401 — "invalid API key"

  • The key was copied with a missing character or an extra space.
  • The key was revoked or has expired — check Console → API keys.
  • Your tool reads the key from an environment variable that is not set in this terminal. Run echo $AIVOKEY_API_KEY (or the variable you used) to check.
  • Claude Code is still signed in to a Claude.ai account: run /logout and restart it.

402 — "insufficient balance" on the first request

A new account has no credit yet. Claim free tokens on the faucet, top up, or buy a plan.

404 — "not found"

  • Wrong base URL. OpenAI-style tools need https://api.aivokey.dev/v1. Claude Code and Anthropic SDKs need https://api.aivokey.dev (no /v1). Getting it wrong produces addresses like /v1/v1/messages.
  • Wrong model id. Copy it from Models. Do not add a provider prefix like openai/ (Aider is the exception — see Other tools & SDKs).

403 — "model_not_in_plan"

Your plan does not include that model. Use a model from your plan, or turn on balance fallback for the key. With Claude Code, set ANTHROPIC_DEFAULT_HAIKU_MODEL too (Claude Code).

402 — "model_allowance_exhausted"

You used up the plan allowance for that model in the current window. The error contains reset_at. Wait, switch model, or turn on balance fallback.

429 — "rate_limited" or "upstream_rate_limited"

Too many requests at once, or the model is busy. Wait the number of seconds in the Retry-After header. Most agents retry automatically.

The agent chats but never edits files or runs commands

The model has no tool support. Choose a model with the tools badge on Models.

"context_length_exceeded"

The conversation is too long for the model. Start a new session, use your agent's compact/summarize command, or pick a model with a larger context window.

Web search is slow

A search takes 20–40 seconds because pages are actually read. That is normal — see Web search & fetch.

Responses are slow to start

Long conversations take longer to process. Prompt caching helps a lot on the second and later turns (Prompt caching).

Still stuck?

Contact support and include:

  • the x-air-request-id response header (or the time of the request),
  • the model id and the tool you use,
  • the full error message.

Never send your full API key — the first characters (sk-aivo_...) are enough.