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.
Confirm the symptom and blast radius
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.
- Capture the status or exception, response body, request ID, UTC time, client version, and final host before changing configuration.
- Compare one minimal request with the failing workflow to determine whether the issue is global, model-specific, or feature-specific.
- Keep credentials, full prompts, customer data, and private file contents out of screenshots and support bundles.
Common causes and ownership boundaries
Treat the error as evidence from one layer, not as proof that every downstream component failed. These are the highest-value causes to test first.
- 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.
Run a layered minimal diagnosis
Start with a request that has the fewest moving parts. Preserve the same account, API host, and target model while removing optional features.
Change one variable at a time and retain the raw status, headers, response body, and timing. This separates client serialization from gateway and upstream behavior.
- 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
Apply the fix at the confirmed root cause
Make the smallest change that addresses the proven layer. Avoid hiding deterministic configuration failures behind broad retries or disabled validation.
- 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.
Verify the repair, not just one successful call
Repeat the original path after the minimal check succeeds, then verify stable behavior under normal streaming, concurrency, and timeout conditions.
- 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.
Security boundaries and escalation evidence
Collect enough evidence to reproduce and escalate the failure without exposing credentials or weakening transport, permission, and validation controls.
- 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.
Read the verification methodology