A 404 from an AI API rarely means the service is down. It almost always means one of two things: the request went to the wrong path, or the model ID you configured does not exist on the platform. A few clients add a third possibility by reporting a permissions mismatch as model_not_found. That is why the fastest route to a fix is checking the endpoint, the model ID, and the key's access together, in that order.
Symptom, Cause, Fix at a Glance
| Symptom | Likely cause | Fix |
|---|---|---|
| HTML-style "page not found" | Base URL path is wrong | Set the base URL to exactly https://zivv.pro/v1 |
model_not_found in the body | Model ID misspelled or retired | Copy the exact id from the live model list |
not_found_error from Claude tools | /v1 wrongly appended to the Anthropic base URL | Use https://zivv.pro for Claude Code, no suffix |
| One model works, another 404s | Key group lacks access to that model | Check the key's group and allowlist in the console |
| Worked before, 404 now | Client kept a stale model entry | Refresh the list and delete old custom entries |
| Client only says "request failed" | Real response is hidden | Open client logs and find the raw status and body |
Read the original response body, not just the popup title. Finding the raw error message usually saves more time than changing settings at random.
Check 1: The /v1 Base URL
OpenAI SDKs, Codex, and most desktop clients expect the base URL to be:
https://zivv.pro/v1The three classic mistakes:
- Entering
https://zivv.prowhen the client does not auto-append/v1 - Entering the full
/v1/chat/completionspath, which the client then appends to again, producing a doubled path - Copying an invisible character or trailing slash along with the URL
The rule: stop the base URL at /v1 and let the SDK add the operation path. All current paths are listed in the endpoint reference.
Claude Code is the deliberate exception, because it speaks the Anthropic protocol:
export ANTHROPIC_BASE_URL=https://zivv.proNo /v1 here — appending it is the mirror image of the mistake above, and it produces not_found_error responses from an otherwise perfect setup. Gemini-protocol tools use a third base: https://zivv.pro/v1beta.
Check 2: The Exact Model ID
A model ID is an identifier, not a marketing name. Case, hyphens, and version suffixes all matter: claude-sonnet-5 is a valid ID, while "Claude Sonnet" is a display name that no API will accept. Never type an ID from memory or from an old tutorial — models get added, renamed, and retired. Pull the live list instead:
curl https://zivv.pro/v1/models \
-H "Authorization: Bearer sk-your-key"Copy the target model's id field verbatim into your client. You can also browse the current catalog with pricing in Model Hub. Current examples include claude-opus-4-8, claude-sonnet-5, gpt-5.5, and gemini-3.5-flash — but always trust the live list over any article, including this one.
Check 3: The Key's Group and Access
A platform can expose several key groups tuned for different workflows — Claude Code via the Anthropic protocol, OpenAI-compatible calls, and so on. A model appearing in the public catalog does not guarantee that every key can reach it. Verify in the console that:
- The key's group includes the target model
- The key has no restrictive model allowlist
- The key is active and unexpired
- The model is served over the protocol your client speaks
The telltale pattern: one key happily calls GPT models but "cannot find" Claude models. That is a group or protocol mismatch, and no amount of client reinstalling will fix it.
Check 4: Stale Client Entries
After a model is renamed or retired, clients often keep the old value in a dropdown or saved profile. Clean it up in order:
- Refresh the client's model list
- Delete stale custom model entries
- Copy the current ID from the live list
- Re-select the provider and the model
- Fully quit and reopen the client
Codex and scripts add one more trap: the model can be defined in project settings, user settings, and an environment variable simultaneously. Keep exactly one source of truth — silent overrides between the three cause 404s that appear to come from nowhere.
Check 5: Reproduce with a Minimal Request
Once the endpoint and ID look right, prove the whole chain with the smallest possible request — no tools, no images, no long context:
curl https://zivv.pro/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{"model":"your-model-id","messages":[{"role":"user","content":"Reply OK"}]}'If this succeeds, the platform, key, endpoint, and model are all working, and the remaining problem lives in the original client's configuration or request payload. If it fails, the error body now tells you precisely which of the two it is — path or model.
FAQ
Q: The model shows in `/v1/models` but requests still return 404. How? A: The listing call and the completion call can travel different configured paths in your client. Usually the chat endpoint has a doubled or missing path segment — recheck Check 1 — or the key's group allows listing but not that model.
Q: Do I need different keys for GPT, Claude, and Gemini models? A: No. One Zivv key covers 100+ models across all three protocols. What changes per protocol is the base URL: /v1 for OpenAI-compatible, no suffix for Anthropic, /v1beta for Gemini.
Q: My client shows a friendly model name. Which string do I send? A: Always the API id — lowercase with hyphens, like gpt-5.5 or claude-sonnet-5. Display names exist for humans; the API only matches IDs exactly.
Q: Could a 404 actually be an auth problem? A: Occasionally — some clients garble a rejected request into the wrong status. If the model ID and path are verified and the 404 persists, run the 401 checklist next; the two guides share the same minimal-request technique.
Wrap-Up
The full checklist: https://zivv.pro/v1 for OpenAI-compatible tools, https://zivv.pro for Claude Code, a model ID copied from the live list, a key group that allows the model, no stale client entries, and a minimal curl reproduction. Field-by-field error semantics are in the error reference. If you are setting up for the first time rather than debugging, start with a fresh key and copy your first model ID straight from Model Hub — the whole class of 404s disappears when IDs are copied, never typed.