OpenAI-compatible error codes: 401 vs 404

Most wasted debugging in this area comes from one confusion: treating a 401 and a 404 as the same kind of problem. Authentication happens before routing, so a 401 says your credential was rejected and nothing about your path, while a 404 says the credential passed and the routing is wrong. Getting it backwards sends you to edit the one thing that was correct.

curl https://aicomp.ai/v1/models \
  -H "Authorization: Bearer sk-your-gateway-key"

The matrix

Status meanings are the HTTP ones. The causes and confirmation steps are specific to routing an OpenAI-compatible client at an endpoint that is not the one it defaults to.

One script, every class

Run this before you start guessing. It establishes a baseline, then separates each class in one request.

#!/usr/bin/env bash
# One script, every error class. Run it before you start guessing.
BASE="https://aicomp.ai/v1"
KEY="$GATEWAY_API_KEY"
MODEL="$1"   # pass a model ID to test the last case

code () { curl -sS -o /tmp/body.json -w "%{http_code}" "$1" -H "Authorization: Bearer $KEY" ${2:+-d "$2" -H 'Content-Type: application/json'}; }

echo "no key      -> $(curl -sS -o /dev/null -w '%{http_code}' "$BASE/models")   (expect 401)"
echo "bad key     -> $(curl -sS -o /dev/null -w '%{http_code}' "$BASE/models" -H 'Authorization: Bearer nope')   (expect 401)"
echo "good key    -> $(code "$BASE/models")   (expect 200 -> key and path are fine)"
echo "bad path    -> $(code "$BASE/v1/models")   (404 here = path shape is wrong)"
echo "bad model   -> $(code "$BASE/chat/completions" '{"model":"does-not-exist","messages":[{"role":"user","content":"hi"}]}')"

# The two that cost the most money, because both look like success:
echo
echo "--- 200 but empty: read the body, not just the status"
curl -sS "$BASE/chat/completions" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Say: ok\"}]}" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print('choices:', len(d.get('choices') or [])); print('usage  :', d.get('usage'))"

echo
echo "--- 429: ask for the reset time, do not assume one"
curl -sS -D - -o /dev/null "$BASE/chat/completions" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Say: ok\"}]}" \
  | grep -iE "^(HTTP/|retry-after|x-ratelimit|ratelimit)" 

The first three lines do the heavy lifting. A request with no key that returns 401 tells you the path resolves and the service is reachable — which means every subsequent 401 is about the credential, and every 404 is about routing. That single baseline removes the ambiguity that makes this error class slow.

The two failures that look like success

Everything in the matrix above announces itself. These two do not, which is why they cost more than any 500.

A 200 with an empty result. A status code reports transport success, not semantic success. The common cause is capability negotiation failing silently: a model that does not support what you asked for returns prose instead of an error, and a client expecting structured output reads nothing. Nothing in your monitoring fires.

A request that was billed but raised. Anything that reached the model consumed input tokens. A timeout, a 5xx, or a cancelled stream can all have been billed while surfacing only as an exception. You cannot tell from the status code — you have to reconcile your request log against the usage record.

Reading a 429 properly

Three conditions return the same status and behave nothing alike:

The message often names a reset time. When it does not, that absence is itself the signal — a limit with no reset time is usually not a time-based limit at all.

What it costs

Rates checked 2026-09-26. Gateway rates move with upstream promotions — verify the current number in your dashboard before committing to a budget.

Rates checked 2026-09-26. Gateway rates move with upstream promotions — verify the current number in your dashboard before committing to a budget. Across the 216 models in our cleaned catalogue the median output-to-input ratio is 4.0×.

Error-handling failures and what each one is actually telling you

When this is the wrong move

Three habits that make error handling expensive

Rolling it out without finding out the hard way

The failure mode you want to avoid is discovering a problem through a production bill or a customer-visible error. Four steps, in order:

1. Prove it on one request per error class, run against a non-critical route. One call, from a script, with an explicit timeout and the model ID echoed back. You are testing reachability, authentication and model availability — three things that can fail independently.
2. Measure before you switch. Record tokens per task and cost per task on the current path first. Without that baseline, "it got cheaper" is an impression, not a result.
3. Move one workload, not everything. Pick the workload with the most predictable shape — batch jobs over interactive traffic. Leave the interactive path on the old configuration until the batch numbers are in.
4. Decide the rollback condition in advance. Write down what makes you revert (error rate above X, cost per task above Y, latency above Z) before you start, so the decision is not made under pressure.

Keep the base URL in configuration, never inline. That single choice is what makes step four take a minute instead of an afternoon.

FAQ

Get API access