# AI provider errors

> What the BYOK key test results and AI provider errors mean, and how to fix them.

Source: https://shopassist.coec.dk/docs/troubleshooting/ai-provider-errors · Updated 2026-10-01

When you save an AI key (or click **Test**), ShopAssist runs a short set of checks against your provider. These checks use a few hundred tokens on your account and are never billed by ShopAssist.

| Check | Required | What it tests | On failure |
| --- | --- | --- | --- |
| `auth` | Yes | The key is accepted (lists models or sends a tiny request) | `auth_failed`, `insufficient_quota`, `gemini_free_tier`, `endpoint_blocked`, `provider_unavailable`, `model_not_found` |
| `tools` | Yes | The model calls a tool with valid arguments and continues after the result | `tools_unsupported`: the model can't run the shopping tools |
| `ttft` | No (degraded) | The first answer event arrives within 8 seconds | `ttft_slow`: works, but shoppers wait |
| `parallel_tools` | No | Two tools are called in one step | `parallel_tools_unsupported`: slightly slower answers |
| `vision` | No | The model names the colour of a test image | `vision_unsupported`: visual search is off |
| `context` | Self-hosted only | A fact at the start of an 8,000-token prompt is recalled | `context_too_small`: the endpoint truncates prompts |

## Common errors [#errors]

### Authentication failed [#auth_failed]

The provider rejected the key (`401`). Check that you copied the whole key, that it is not revoked and that it belongs to the selected provider. For Azure OpenAI, check the resource name; for OpenAI-compatible endpoints, check the base URL.

### Insufficient quota [#insufficient_quota]

The provider returned `429` with a quota or billing error. Add credit or raise the limit in your provider account. Rate-limit errors during busy hours are retried automatically, and the [fallback model](/docs/ai/choose-your-ai#fallback) is used if you set one.

### Gemini free tier [#gemini_free_tier]

Google's free tier may use your data to improve its products and is not accepted. Use a key from a project with billing enabled.

### Model not found [#model_not_found]

The model id does not exist for your key. For Azure, enter the **deployment name**, not the model name. Some models need access approval first.

### Tools unsupported [#tools_unsupported]

ShopAssist needs a model that supports tool (function) calling. Choose a model from the recommended list, or for self-hosted models enable tool calling (vLLM: `--enable-auto-tool-choice --tool-call-parser <parser>`; LM Studio: a model with a tool chat template).

### Context too small [#context_too_small]

Self-hosted models must accept at least about 16,000 tokens of context. For Ollama, set `PARAMETER num_ctx 16384` or higher in the Modelfile.

### Endpoint blocked [#endpoint_blocked]

The base URL is not a public HTTPS address on port 443, or it resolves to a private network. Expose your endpoint on a public HTTPS URL behind authentication.

### Slow first response [#ttft_slow]

The model took more than 8 seconds to start answering. The key works but the configuration is marked **degraded**. Choose a faster model or a closer region.

### Provider unavailable [#provider_unavailable]

The provider had an outage or timed out. Try again later. During live conversations, ShopAssist retries and then uses your fallback, or shows the shopper a contact option.

## What shoppers see [#shoppers]

Shoppers never see provider errors. When AI is unavailable the widget offers a handoff or a contact form. The dashboard shows a banner and owners get an email when a key stops working.