Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsIf an AI agent stopped working after you placed a credential gateway or corporate proxy between it and its model provider, first identify which layer failed. Then trace the request from the process that launches the agent, through gateway authentication and routing, to the provider. A gateway can introduce a second credential boundary, a different endpoint or header requirement, and a new network or TLS path—so an error does not automatically mean the agent’s API key is wrong.
Before changing settings, record the agent and gateway versions, endpoint type, deployment surface, exact status and error, timestamp, and a redacted request or trace ID. Never include token values, authorization headers, or sensitive prompts in shared diagnostics.
As an Amazon Associate I earn from qualifying purchases.
Why did my AI agent stop working after I added a gateway?
A gateway sits between the agent and model provider, so the request may need to pass two separate authentication checks: the agent authenticates to the gateway, and the gateway authenticates to the upstream provider. The gateway may also change the endpoint, route, model naming, or network path. Start by locating the failure rather than replacing credentials at random.
Capture these details before editing configuration:
#1 Best Overall
- Agent/client name and version, gateway product and version, provider, and requested model.
- Endpoint type and base URL, with credentials and sensitive path components redacted as needed.
- Where the agent runs: shell, desktop app, service, worker, or container.
- Exact HTTP status and error code/message, timestamp, and redacted request or trace ID.
- Whether the failure occurs before a turn starts, during a turn, during session or environment setup, or while a tool/server initializes.
Keep enough information to correlate the request with gateway and provider logs, but do not disclose secrets or private prompt content. A changed error after one configuration change is useful evidence; repeated blind retries are not.
Find which layer is failing
Separate a rejected API request from a failure after the agent has accepted the request. OpenAI’s Agents API guidance distinguishes request errors, turn and session failures, and runtime environment errors; use the equivalent status and diagnostics exposed by your agent and gateway.
- Request creation/API error: Inspect the HTTP status and response error object, including its code, message, and parameter when present.
- Turn failure after acceptance: Inspect the failed turn’s status and error details. The request may have been accepted even though the work did not complete.
- Session or environment failure: Inspect session/environment error details, including connectivity and startup setup.
- Tool or MCP initialization failure: Identify the named tool or server and inspect its startup configuration and credentials.
Common categories help narrow checks but do not, by themselves, prove the gateway caused the problem. A 401 generally indicates authentication failure; a 403 indicates insufficient access or a policy denial; a 404 or model-not-found response points toward an unavailable resource or route; a 424 MCP startup failure points toward server configuration or credentials. Connection errors and timeouts point toward connectivity or service conditions.
Why am I getting a 401 after adding an LLM gateway?
Trace the credential path on both sides of the gateway. The credential the agent presents to the gateway may not be the provider’s API key, and the gateway’s upstream credential may be stored and selected separately.
- Identify which credential the agent is meant to present to the gateway.
- Find how the client reads it: environment variable, command/helper, or configured header.
- Verify that the credential is available to the process that actually launches the agent.
- Confirm that the gateway accepts it for the intended route, project, tenant, or account.
- Confirm that the gateway has a valid upstream provider credential with permission to use the selected model.
Credential availability is a frequent source of differences between environments. A variable set in an interactive terminal may not be inherited by a desktop-launched app, service, or container. Restart the relevant process after changing its environment or secret delivery configuration, and verify effective variable names or credential-helper behavior without printing secret values.
Keep credentials out of source files, committed configuration, terminal transcripts, screenshots, and logs. OpenAI’s Codex gateway guidance describes environment-variable, custom-header, and command-helper patterns for making a secret available to the launching process; use your organization’s secret-delivery mechanism rather than embedding the value in a repository or TOML file.
For Claude Code specifically, Anthropic documents that an active gateway credential replaces the developer’s Claude subscription login for those requests, and usage is billed to the owner of the forwarded gateway credential. Setting ANTHROPIC_BASE_URL to a gateway does not itself provide a gateway credential. Do not assume the gateway token is inferred from the URL or from a subscription login.
Recommended Free Tools
Check the exact header and endpoint type
Authentication headers are not interchangeable. Confirm the endpoint family your client is actually calling, then match the gateway’s documented header name, scheme, and credential role exactly. Common patterns include Authorization: Bearer …, x-api-key, and vendor-specific headers, but the correct choice depends on the endpoint.
Cloudflare’s documentation illustrates why endpoint type matters: its provider-native gateway endpoints use cf-aig-authorization for Cloudflare gateway authorization, while its REST API uses the standard Authorization header. For the documented Cloudflare gateway setup, the Cloudflare token belongs in cf-aig-authorization; Authorization is reserved for the provider credential. Check the current instructions for the endpoint you use rather than copying a header recipe from another API.
Inspect the final outgoing request at the gateway edge using redacted diagnostics. Look for a missing, duplicated, stale, or overridden authentication setting, especially if the client has its own precedence rules. Record header names and whether the expected credential is present; never log or paste the credential itself.
Why does the gateway return model not found?
Successful authentication does not guarantee that the request reached the intended model. Check the complete route from the client’s base URL to the gateway’s upstream provider:
- Confirm the base URL host and path, and that the client is using the API format supported by that endpoint.
- Check the provider-specific path or route and any required provider prefix in the model name.
- Verify the model identifier’s spelling and that the model is enabled for both the gateway account and upstream provider.
- If the gateway has multiple stored or bring-your-own-key (BYOK) credentials, confirm which key or alias the route selected and whether it is the intended default.
Cloudflare documents different routing conventions for provider-specific endpoints and its unified compatibility endpoint; the latter uses provider-prefixed model names. Compare the request URL with secrets removed, the model field, and the gateway routing log to identify where the route diverges.
Gateways can also differ in API-format and feature compatibility. If a new tool or client feature broke after insertion, check whether the gateway supports and forwards that API behavior and any required headers. Anthropic cautions that third-party gateways are operated independently and are not endorsed, maintained, or audited by Anthropic; compatibility can change as clients add features.
How do I fix certificate or TLS errors behind a corporate proxy?
Test from the same runtime and network that launches the agent. A successful request from a developer’s workstation does not establish that a service, desktop app, or container can resolve or reach the same host, or trust the same certificate chain.
- Check DNS resolution and reachability to the gateway and required provider endpoints from the agent’s runtime.
- Check firewall and proxy allowlists, proxy reachability, and any required proxy authentication.
- Determine whether the corporate proxy performs TLS inspection and whether the runtime trusts the organization’s root certificate.
- Compare the runtime’s certificate store and version with the requirements of the agent’s networking stack.
For Claude Code, Anthropic documents trust of bundled Mozilla and operating-system CA stores by default. Reading the OS certificate store requires a runtime that supports tls.getCACertificates; for npm installations, the documentation specifies Node 22.15 or later. On older Node versions, NODE_EXTRA_CA_CERTS is a documented configuration path. These are Claude Code-specific instructions, not universal settings for every agent.
Anthropic’s Claude Code corporate proxy guidance also covers basic proxy authentication and disabling gzip request bodies when a TLS-inspection proxy mishandles compressed bodies. Apply those settings only when they match the observed failure and the agent’s own documentation. Avoid hardcoding proxy passwords; use environment variables or secure credential storage.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Use logs and controlled tests to isolate the break
Correlate the client timestamp and request ID with gateway access/error logs and provider-side diagnostics. Establish, in order, whether the request reached the gateway, whether gateway authentication passed, which route and upstream key were selected, and what status the provider returned. Cloudflare recommends reviewing AI Gateway logs, checking provider credentials and provider status, and reviewing rate-limit settings for timeout or request failures.
If possible, compare one redacted request through the gateway with a known-good provider-native request from the same runtime and network. Change one variable at a time. Compare credential presence, scope, key alias, header name, permissions, endpoint, and model—not secret contents. If the gateway never receives the request, focus on the client environment and network path; if it receives but rejects it, focus on gateway authentication or policy; if it forwards and the provider rejects it, inspect upstream credentials, route, model, and provider permissions.
Error-to-check map
| Symptom | First checks | Evidence to inspect |
|---|---|---|
| 401 / unauthenticated | Credential available to the actual process; exact header and scheme; gateway token versus provider token; scope or expiry. | Client error body, gateway authentication log, and redacted final header names. |
| 403 / forbidden | Account, project, model, route, organization permission, or gateway policy. | Error code/message and gateway policy log. |
| 404 / model not found | Base URL/path, provider route, model spelling and availability, and required model prefix. | Request URL with secrets removed, model field, and gateway routing log. |
| TLS/certificate error | Runtime CA store, installed organization root CA, NODE_EXTRA_CA_CERTS where applicable, and proxy inspection. |
Runtime version, certificate chain, and proxy configuration. |
| Timeout / connection failure | DNS, egress and allowlist, proxy reachability, provider status, and rate limiting. | Client timeout, gateway logs, and provider status. |
| Works in shell but not desktop or service | Process environment inheritance, credential-helper path and permissions, and whether the app was restarted. | Launch context and effective environment variable names, never secret values. |
| New feature or tool breaks after gateway insertion | Gateway API compatibility and forwarding of required headers/features. | Current gateway compatibility documentation and request logs. |
Retry only after checking what already happened
Fix invalid credentials, permissions, endpoint settings, and billing limits before retrying. For rate limits, overload, timeouts, or temporary service failures, first determine whether a session or turn was created and inspect saved work and completed actions. A failed turn may already have invoked tools or changed files, so repeating it can duplicate side effects. When retrying a transient failure, honor the service’s retry timing and impose an attempt limit.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →If the gateway itself is the mismatch
When the evidence points to an incompatible or operationally unsuitable gateway, evaluate alternatives against the work the gateway must do rather than choosing on a generic feature list. Compare supported API formats and client compatibility; credential and header mapping; secret delivery; provider/model routing; observability and redaction; rate limits and budget controls; deployment and maintenance burden; and how quickly compatibility guidance is updated. Gateways may offer credential centralization, usage tracking, cost controls, audit logging, or provider switching, but the organization operating one is responsible for keeping it secure and compatible with its clients.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
