DEV Community

NiceAI
NiceAI

Posted on Edited on AI-assisted

Pointing Claude Code and Codex at a custom API endpoint: the /v1 rule behind most 404s

Disclosure: I write docs for an API relay, and I use its endpoint in the examples. Everything here works the same with any Anthropic- or OpenAI-compatible gateway.

TL;DR

  • Claude Code: ANTHROPIC_BASE_URL is the host only. No /v1.
  • Codex CLI: base_url ends with /v1.
  • If you get a 404, count the /v1s in the URL from the error.

Why they differ

Each client appends a different path to whatever you give it:

Client You set Client appends Final request
Claude Code, Anthropic SDK https://api.example.com /v1/messages /v1/messages
Codex CLI, OpenAI SDK, Cursor, Cline https://api.example.com/v1 /responses or /chat/completions /v1/responses
Gemini CLI https://api.example.com /v1beta/... /v1beta/...

So /v1 on Claude Code gives you /v1/v1/messages, and no /v1 on Codex gives you /responses. Both are 404s.

Claude Code setup

Put it in ~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json) so it applies however you launch Claude Code:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.niceai.dev",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key"
  }
}
Enter fullscreen mode Exit fullscreen mode

Notes:

  • ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer. ANTHROPIC_API_KEY is sent as x-api-key. Use the one your provider documents, not both.
  • Restart Claude Code after editing; a running session keeps the old values.
  • Run /status inside Claude Code. The Anthropic base URL line should show your endpoint. If the line is missing, the variable never reached the session.
  • Don't put keys in a project's committed .claude/settings.json.

Codex CLI setup

~/.codex/config.toml:

model = "a-model-name-from-your-provider"
model_provider = "myrelay"

[model_providers.myrelay]
name = "My Relay"
base_url = "https://api.niceai.dev/v1"
wire_api = "responses"
env_key = "MYRELAY_API_KEY"
Enter fullscreen mode Exit fullscreen mode
export MYRELAY_API_KEY="sk-your-key"
codex
Enter fullscreen mode Exit fullscreen mode

Three gotchas:

  1. model and model_provider must sit above the first [table]. Put them under [model_providers.myrelay] and Codex silently uses its default model.
  2. openai, ollama and lmstudio are reserved provider IDs.
  3. Current Codex only speaks the Responses API. "OpenAI compatible" doesn't guarantee /v1/responses exists, so check.

Test with curl before blaming the client

# Anthropic Messages (what Claude Code uses)
curl -sS -w '\n%{http_code}\n' https://api.niceai.dev/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"a-model-name","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
Enter fullscreen mode Exit fullscreen mode

How to read the result:

  • JSON with content: URL and key are fine, the problem is client config.
  • HTML or 404: wrong URL.
  • JSON 401: right URL, wrong key.
  • "model not found": URL and key are fine, wrong model name.

Quick error table

Error Likely cause Fix
404 /v1/v1/messages /v1 in ANTHROPIC_BASE_URL remove it
404 .../responses missing /v1 in Codex base_url add it
401 bad key, stray whitespace re-copy the key
403 key valid but no access (balance, model group) check balance and key permissions
429 rate limited fewer parallel sessions/subagents
529 overloaded_error upstream busy wait, or switch model with /model

The endpoint in the examples is NiceAI, which I work on: https://niceai.dev (setup docs for more clients at https://wiki.niceai.dev/en/).

Top comments (0)