Where my first request died: one config line, three names

Context: I run a CLI agent against one gateway. The whole setup is one provider block in one config file — and three different things in that block are called some kind of "name". I got them mixed up on 23 September 2026, and it cost me an evening.

What I did

I pasted the provider block, exported the key, and sent a request.

# ~/.codex/config.toml
model_provider = "decloud"

[model_providers.decloud]
base_url = "https://macdecloud.com/v1"
env_key  = "DECLOUD_API_KEY"   # a NAME, not the secret
wire_api = "responses"

What broke

My first request died on a 404 that reads like a broken model:

model not found or disabled    (HTTP 404)

The model was fine. The alias it pointed at had not been created yet — the third of the three names. In this setup a 404 means "this name is not known here", and one of the three names is a name I had to create myself before the first call.

Then the other two names turned out to be confused with each other.

1. env_key wants the variable's name; I pasted the secret. The field is called env_key, so it reads like it wants a key. It wants the name of the environment variable that holds the key:

Missing environment variable

2. An alias is not a permission. Once the alias existed, the call still failed:

model "<alias target>" is not allowed for this api key    (HTTP 403)

3. There is no endpoint that answers "what may this key call". I went looking for a cheap way to ask. /v1/me, /v1/key and /v1/usage all came back 404. The answer lives in the console, not in the API.

The two codes are not the same question

This was the most useful thing I wrote down all evening. Both numbers arrive attached to the model name, and they mean opposite things:

What came back	Code	What it means	What to change
model not found or disabled	404	this name is not known here	create the alias, or fix the model id
... is not allowed for this api key	403	the model exists; this key may not use it	the key's own model scope
Missing environment variable	—	the variable the config names does not exist	env_key vs what you exported
rate limit exceeded	429	too fast	slow the probe down

The catalogue endpoint makes this worse before it makes it better. It returns the gateway's full list, and I quietly assumed that a listed model was a usable model. It is not. A catalogue describes what exists; a permission list describes what you may call. Only one of those two is written in the config file.

How I fixed it

I stopped treating the block as "fields to fill" and wrote down the three names and their jobs:

• one name is the credential's name — the environment variable (env_key → DECLOUD_API_KEY);
• one is the secret — the value inside that variable, exported in the shell, never written into the file;
• one is the alias — the model name the request carries, which the key must separately be allowed to use.

With that mapping written down, every failure turned into a question I could answer: which of the three names does this error belong to?

What I would do differently

One line, before touching anything:

cp config.toml config.toml.bak

I did not, and an editor save accident wiped the file mid-session. The only reason that evening ended with a working setup instead of a rebuild is that an earlier backup existed. A config file for a developer tool accumulates months of small decisions; it is not disposable.

Takeaways

1. Read the error, not the sentence you expected. Missing environment variable is about a name, not about the secret.
2. A catalogue is not a permission list. Check the key's own scope before you touch the model name.
3. Back up the config before you edit it — and if the API cannot tell you what a key may call, write that answer down from the console once.