API key invalid and model discovery 404: provider errors

API key invalid and model discovery 404 are two layers: "who you are" and "which models exist." Mixing them leads to swapping keys when the real problem is the base URL.

Two errors, separate first

The symptoms look similar; the tests differ.

Authentication asks "do you have permission"; endpoint failure asks "is the address right." Both break requests, but the fixes are different.

pi_ai_error is not the root cause. It is a fallback label with detail behind it; staring at the label hides the error.

Layer one: key and permissions

Check value, scope, and state.

1. Value: complete copy, no spaces or newlines.
2. Scope: permission to call the target model.
3. State: expired, revoked, or out of balance.
4. Environment: whether the session actually reads this key, not an old value.
5. Provider: the key and base URL belong to the same service.

Keys and endpoints must pair. Using provider A's key with provider B's URL always fails authentication; it looks like a bad key, but it is a mixed configuration.

Restart or reload after changing a key. A running process may hold the old value.

Layer two: model discovery and address

Check address, path, protocol, and support.

1. Address: protocol, host, and port.
2. Path: whether the base URL includes an extra /v1 or misses a version segment.
3. Protocol: OpenAI-compatible or provider-specific.
4. Support: whether the service offers a model list endpoint; if not, it returns 404.
5. Network: whether a proxy or gateway rewrites the request.

Base URL syntax is the most common mistake, and 404 is not a bad key. Authentication failures usually return 401 or 403, while 404 points to address or path; read the status code before changing configuration (source).

Recovery: skip discovery, enter manually

When the model list fails, manual entry is the fastest recovery.

1. Find the skip-discovery option or its equivalent.
2. Enter the model identifier exactly as documented.
3. Save and open a new session for a test message.
4. Confirm success, then fix the list endpoint later.
5. Return to automatic discovery once it works.

Manual entry does not reduce usability. Automatic discovery is convenience; working matters more than a populated list. Match the name character for character: case, version suffix, and namespace all matter.

Three common misreads

Three reactions waste time.

1. Swapping keys repeatedly. With a wrong address, ten keys still return 404; determine authentication versus endpoint first.
2. Reinstalling. Configuration does not change; the same key and address return.
3. Deleting the session. Session data and provider configuration are separate; deletion does not fix 404.

All three skip the status code. 401 and 404 point to different layers; read them first.

Collect evidence before changing. Record the full error, request address, and time.

Verify after fixing

Three checks, not just "saved."

1. Authentication: no more 401 or 403.
2. Model: the list loads or the manual model works.
3. Request: a new session replies, and logs show the right address and model.

All three must pass. Passing only the first may mean a different error remains.

Keep a fix record. What changed, to what value, and the result; reuse it next time.

Prevention: separate configuration layers

Three habits keep provider configuration clean.

1. One provider, one configuration: do not mix keys and addresses.
2. Back up before changing: record file locations and key placement.
3. Change one item at a time: address, key, and model separately.

Configuration is infrastructure, not a one-time setup. Records beat guessing.

Next steps

Read the status code, then fix the layer. For general key errors, read API key error troubleshooting. For incomplete model lists, read Model list incomplete. For provider setup, read How to configure models.

Sources: DeepSeek Harness docs, dsh CLI README, deepseek-harness repository