SUPPORTING KNOWLEDGE · 0011
Provider errors mean four things¶
A provider is the credentialed connection between a model and Berd. When you save a provider's credentials, Berd immediately fetches that provider's live list of models. That fetch is not decoration: it is the verification. It checks the key, the URL and the network in one request, so if the model list appears, the provider works.
If it does not, Berd maps whatever the provider said back into one of four causes. Its help skill calls this mapping deliberate, documented behaviour rather than an implementation detail, which is why it is safe to learn:
| What you see | What it means | What to do |
|---|---|---|
| 401 / 403, "unauthorized", "invalid API key" | The credential itself was rejected | Re-check the key. Nothing else is wrong |
| 404, "not found" | The server answered, but the path was wrong. Most often a missing /v1 on a custom provider URL |
Fix the URL, usually by adding the suffix |
| Connection refused, timeout, DNS failure, "network error" | Nothing answered at all | Check the URL, your network, and whether the provider's service is up |
| 429, "rate limit", "too many requests" | The key works; the provider is throttling you | Wait, or change plan. This is not a configuration problem |
Why it matters to you¶
Faced with "the key doesn't work", the usual reflex is to regenerate it, re-paste it and reinstall. Only the first row calls for a new key. The second is a URL. The third is not Berd or the key. The fourth means you have succeeded and are being asked to slow down.
The mapping also marks the boundary. Everything in the table is Berd's to explain, because it is the app talking to a provider. What a model does once the connection works is the harness's domain; see App vs harness.
Two edges the help skill names. Providers set up through a CLI installer fail differently, with a narrower taxonomy: a file already exists at the target path, or the operating system and architecture are not supported. And which providers are offered ready-made versus custom-only changes too often for the help skill to state from memory; the Coach does not state it either.
One rule sits behind all of this: an agent cannot be invoked without a configured provider and model. A provider error blocks everything downstream, including — in distributions that enable automations — an automation being drafted, which runs on a provider like any other chat.
How to apply it¶
Read the number before you touch anything. Find the status code or the phrase in the error, match the row, do only that row's action.
When you add a custom provider URL, expect the 404 and check the suffix first. It is the one the help skill singles out.
If the error is 429, stop retrying. Retrying a throttled key is how a temporary limit becomes a longer one.
When an automation fails (in a distribution that enables them; the v0.6.4 public build does not), ask which phase failed before blaming the provider: drafting in the builder chat runs on a provider and can hit any of the four; approving or saving the tile is a product step and its failures are not in this table. See Automations: built by talking, failing in two places.
Pick the model in the chat toolbar once the provider is verified; recently used models sit near the top of the picker, and you can switch mid-chat when the task changes.
If you ignore this¶
You regenerate a working key three times because the custom URL was missing /v1. Or you open a support thread about an "authentication failure" that was a rate limit, and it resolves itself while you wait, teaching you nothing.
Examples¶
Four ways a phone call fails: wrong PIN (401), right building but wrong extension (404), no dial tone (connection), and "all our lines are busy" (429). Only the first is about your credentials.
A consultant adds a self-hosted OpenAI-compatible endpoint, saves the key, and gets 404. The URL ends in the hostname. Adding /v1 makes the model list appear; nothing else was wrong.
Treating "429 too many requests" as a broken key and creating a new one. The provider was saying yes, slower.
Do it: Connect a provider and pick a model
Last checked: Berd v0.6.4, 2026-09-11.
Reference¶
- block/berd — distro/skills/berd-help/references/ai-providers.md — the four causes, the live model-list fetch, the CLI-installer taxonomy
- block/berd — LAWS/AGENTS.md — provider and model before invocation
- block/berd — distro/skills/berd-help/references/automations.md — which failure phase is a provider problem
- block/berd — CHANGELOG.md — v0.6.3, model picker recency
- Verified
- Berd v0.6.4 · 2026-09-11