Direct answer
A 404 can refer to the URL path or to a model identifier. Inspect the response type first, then copy the model ID from the same account and API origin.
What this guide helps you solve
Fix wrong API paths, stale model aliases, unavailable model IDs, and gateway routing errors that return 404.
Symptoms
The response is either an HTML/plain route 404 or structured JSON that names a missing model.
A model name copied from marketing material or another provider fails while IDs returned by the current model catalog work.
Likely causes
- The base URL contains a duplicated, missing, or incorrect API version path.
- The model ID has the wrong case, prefix, date suffix, provider namespace, or alias.
- The account or route does not expose that model even though another tenant does.
- A client provider name maps to a gateway route that does not contain the selected model.
Diagnostic procedure
- 01Establish the boundaryClassify the response as route-level HTML/plain text or a structured model error.
- 02Create a baselinePrint the final sanitized API URL and confirm the version appears once.
- 03Compare one variableList models with the same host and credential, then copy the exact ID.
- 04Record decisive evidenceCompare the client provider and gateway mapping with a direct curl request.
API_BASE_URL='https://<your-api-host>/v1'
curl -sS -D /tmp/model-headers.txt "$API_BASE_URL/models" -H "Authorization: Bearer ${API_KEY:?set API_KEY first}" -o /tmp/models.json
sed -n '1,20p' /tmp/model-headers.txt
Remediation
- 01Correct the failing layerCorrect the API root so model discovery and generation share the same origin.
- 02Restore required behaviorReplace stale aliases with the exact account-visible model ID.
- 03Remove temporary workaroundsUpdate the client provider or gateway mapping without inventing an unsupported alias.
Verification
- Model discovery and generation use the same API root.
- The ID matches case, prefix, namespace, and version exactly.
- Both curl and the target client succeed with that same ID.
- Old aliases are removed from local config, CI secrets, templates, and documentation.
Sensitive diagnostic data
- Do not expose the full model catalog if it contains private deployment names.
- Keep credentials out of model-list debugging output.
- Do not silently redirect an unknown model to a different capability tier.
- Escalate with the exact sanitized route, model ID, response type, and request ID.
Official sources and verification scope
This guide is grounded in protocol specifications and official client documentation. Error text, retry headers, and configuration fields may change by service or client version; verify the sources and redact logs and request samples before sharing.
View documentation scope