A 401 from a relay usually means the request reached an authentication check, but the credentials were missing, invalid, or unacceptable to that endpoint. It is not, by itself, evidence that your prompt is wrong or your chosen model is unavailable. Work through this checklist before changing models, adding retries, or rebuilding your integration.
1. Identify which service returned the 401
Start with the failing request, not the application's final error message. Record the destination hostname, HTTP status, response body, and any request identifier. A CLI might wrap an authentication failure in a broader connection error, while an SDK might expose the useful details only in its exception object.
Check whether the response came from the relay, a corporate gateway, or an upstream service. A relay can also pass along an upstream authentication failure. The status alone does not identify which credential failed. Keep diagnostic records private and remove secrets before sharing them.
2. Match the credential to SwiftRelay
For a SwiftRelay request, use a key issued by SwiftRelay. A direct provider key should not be assumed to authenticate with a relay, even when the model name and request format look familiar. Likewise, a relay key should not be sent to a provider's direct endpoint.
If you need a relay account, sign up for SwiftRelay and create a key for your integration. SwiftRelay supports tools such as Claude Code, Codex, and Gemini CLI, alongside OpenAI-compatible SDKs. That compatibility still requires the correct pairing of endpoint, credential, and client configuration.
3. Check that the running process received the key
A key saved in your shell profile is not necessarily available to an already-running editor, container, background service, or terminal session. Confirm that the process making the request reads the intended setting. Do not assume every client uses the same environment variable name.
- Check whether a project configuration overrides your global settings.
- Look for an old key stored in the client's credential settings.
- Remove accidental spaces, line breaks, or literal quotation marks.
- Restart the relevant process after updating its environment.
For diagnostics, report whether a key is present, not its full value. Never paste the credential into an issue, screenshot, or support conversation.
4. Verify the API host and path
SwiftRelay's API host is https://api.fastapirelay.com. Claude Code and Gemini CLI take that bare host. For an OpenAI-compatible SDK, configure the base URL as https://api.fastapirelay.com/v1.
Inspect the actual destination after configuration is applied. Watch for a provider hostname left over from an earlier setup, a duplicated /v1 segment, or an endpoint path placed where the client expects only a base URL. Path mistakes often produce other errors, but checking the destination prevents you from debugging credentials against the wrong service.
5. Inspect the authentication mechanism without exposing it
OpenAI-compatible requests normally authenticate through an Authorization header using the Bearer scheme. Other client integrations may use different headers or authentication settings. Follow the instructions for that client rather than manually applying one header format everywhere.
If a proxy sits between your application and the relay, check whether it strips or replaces authentication headers. Also check for duplicate authorization settings: a stale custom header can conflict with the key supplied through an SDK. Inspect header names and configuration sources while keeping credential values redacted.
6. Run one minimal request outside the failing workflow
Use a supported client with the verified endpoint, the intended key, and a short prompt. Choose a model available to your account, such as Claude Haiku 4.5, without adding tools, attachments, or custom middleware.
If the minimal request succeeds, compare its settings with the failing application. If it still returns 401, review the error body and check whether the key was revoked or replaced. Creating a fresh key can help isolate a credential problem; revoke obsolete keys afterward.
7. Escalate with evidence, not repeated retries
Repeatedly sending the same unauthorized request will not repair its credentials. Give support the timestamp, hostname, client version, sanitized error body, and request identifier when available. Mention whether the minimal request succeeded.
Keep billing and authentication diagnoses separate unless the response explicitly connects them. SwiftRelay bills per token, but a generic 401 is not proof of an account-balance issue. Let the response details guide your next action.