AI provider errors
What the BYOK key test results and AI provider errors mean, and how to fix them.
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
Authentication 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
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 is used if you set one.
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
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
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
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
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
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
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 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.
Last updated on