Provider Troubleshooting

QARK surfaces provider errors with specific codes and messages. This page covers the most common issues and how to resolve them.

Invalid API key

Error: “Authentication failed,” “Invalid API key,” or “Unauthorized.”

• Extra whitespace — copy-pasting often adds a leading or trailing space. Trim the key before saving.
• Wrong provider — an OpenAI key won’t authenticate against Anthropic’s API. Confirm you’re entering the key in the correct provider’s settings.
• Expired key — some providers issue keys with expiration dates. Generate a new one from the provider’s dashboard.
• Still failing — revoke the key on the provider’s dashboard and create a fresh one.

Rate limits

Error: “Rate limit exceeded,” “Too many requests,” or HTTP 429.

Rate limits are set by the provider based on your plan tier — requests per minute, tokens per minute, or both. Solutions:

• Wait for the cooldown period (usually 60 seconds).
• Reduce request frequency — avoid rapid-fire sends.
• Upgrade your plan with the provider for higher limits.

Not the same as QARK budget limits. See the comparison table below.

Model not found

Error: “Model not found,” “Invalid model,” or “The model does not exist.”

• Model renamed — providers occasionally rename or version models. Refresh the model list to pull current names.
• Plan restriction — some models require a paid tier or waitlist access. Check your provider account’s model access settings.
• Stale cache — QARK caches the model list for 5 minutes. Force a refresh: Settings → Providers → [Provider] → Refresh Models.

Request timeouts

Error: “Request timed out,” “Connection timeout,” or responses that never arrive.

• Large context — sending 100K+ tokens takes longer to process. Reduce context size or switch to a model with faster processing.
• Slow model — frontier reasoning models (Claude Opus, GPT-5 Pro, DeepSeek R1) can take 30–60 seconds for complex prompts. This is expected, not an error.
• Network issues — verify your internet connection. If you’re behind a VPN or firewall, confirm it allows outbound HTTPS to the provider’s API endpoints.

OpenAI organization IDs

Error: “Invalid organization” or requests billed to the wrong org.

If your OpenAI account belongs to multiple organizations, you need an organization ID in addition to the API key. Find yours at platform.openai.com/account/org-settings and enter it in Settings → Providers → OpenAI → Organization ID.

Single-org accounts can leave this field empty — OpenAI defaults to your primary org.

Google Gemini setup

Error: “API not enabled,” “Permission denied,” or “Project not found.”

The fastest path is through Google AI Studio:

1. Go to aistudio.google.com.
2. Click Get API Key.
3. Create a key (or select an existing project).
4. Paste the key in QARK.

If using Google Cloud Console instead, you need to enable the “Generative Language API” under APIs & Services → Library before generating a key under Credentials.

Ollama not connecting

Error: “Connection refused,” “Cannot connect to Ollama,” or timeout.

Ollama runs as a local service. QARK can’t connect unless it’s actively running.

1. Start the service — run ollama serve in your terminal, or launch the Ollama desktop app (system tray on macOS/Windows).
2. Verify — open http://localhost:11434 in your browser. You should see a response confirming Ollama is active.
3. Check the port — if you configured Ollama on a non-default port, update the endpoint in QARK’s provider settings.
4. Pull a model — run ollama pull llama3.2 so there’s at least one model available for QARK to list.

Force a model list refresh

QARK caches each provider’s model list for 5 minutes. If a provider has added or removed models and the change isn’t reflected:

1. Open Settings → Providers → [Provider].
2. Click Refresh Models.
3. The cache clears and QARK fetches the current list.

This also resolves stale pricing or capability data.

Budget limits vs rate limits

These produce different errors and have different solutions:

	QARK budget limit	Provider rate limit
Set by	You, in QARK settings	The provider, based on your plan
Triggers at	Monthly spending cap (80% warning, 100% block)	Requests/tokens per minute exceeded
Error	”Monthly budget exceeded for [provider]"	"Rate limit exceeded” / HTTP 429
Fix	Increase limit in Settings → Budget, or switch provider	Wait for cooldown, reduce frequency, or upgrade plan

If you’re unsure which limit you hit, check Settings → Budget first. If your budget has remaining balance, the issue is provider-side.