Errors & Debugging

This page is the complete reference for failures on the Nexotao API: the shape of an error body, what each code means, which ones are worth retrying, and how to trace a single request after the fact.

Base URL: https://api.nexotao.com.

The error envelope

Every API error is returned as a single JSON object with the same shape, regardless of the endpoint.

{
  "error": "invalid api key",
  "code": "auth.api_key_invalid",
  "type": "api_key_invalid",
  "request_id": "8997bda3-65c4-45c3-ab38-c909f905fc4d",
  "retryable": false
}

Two headers accompany every error response:

Reading the error code

curl -sS -D /tmp/h.txt https://api.nexotao.com/v1/chat/completions \
  -H "Authorization: Bearer sk-nexo-FAKE-EXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"hi"}]}'
 
grep -i '^x-error-code\|^x-request-id' /tmp/h.txt

import httpx
 
r = httpx.post(
    "https://api.nexotao.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-nexo-FAKE-EXAMPLE"},
    json={"model": "claude-sonnet-4-6",
          "messages": [{"role": "user", "content": "hi"}]},
)
 
if r.status_code >= 400:
    body = r.json()
    print(body["code"], body["request_id"], body["retryable"])
    # headers alone are enough, no body parsing needed:
    print(r.headers["x-error-code"], r.headers["x-request-id"])

const res = await fetch("https://api.nexotao.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-nexo-FAKE-EXAMPLE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    messages: [{ role: "user", content: "hi" }],
  }),
})
 
if (!res.ok) {
  const body = await res.json()
  console.error(body.code, body.request_id, body.retryable)
  console.error(res.headers.get("x-error-code"), res.headers.get("x-request-id"))
}

request_id

Every request — successful or not — gets a unique request_id, sent in the X-Request-Id header and recorded server-side.

• On error responses the same id also appears in the body as request_id.
• Log it in your application. When reporting a problem, one request_id is far more useful than a screenshot of the error message.
• For streaming requests, X-Request-Id is sent before the first stream byte, so it is still readable when a stream fails mid-flight.

curl -sS -D - -o /dev/null https://api.nexotao.com/v1/messages \
  -H "Authorization: Bearer sk-nexo-FAKE-EXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":16,
       "messages":[{"role":"user","content":"hi"}]}' \
  | grep -i x-request-id

Error code catalogue

Grouped by HTTP status. The Retry column is the retryable field in the body.

400 — Invalid request

401 — Authentication failed

402 — Balance

This check runs before the request is forwarded to a model, so a request rejected with 402 is never charged.

403 — Forbidden

404 / 405 — Routing

413 — Body too large

429 — Rate limits and quotas

On the API-key path, responses also carry rate observability headers when the relevant limit is active for that key:

5xx — Server-side failures

In-band streaming errors

This is the easiest thing to miss in the whole API.

The error event’s wire shape depends on the endpoint:

data: {"error":{"message":"upstream service unavailable after retries; please retry","type":"server_error","code":"upstream_unavailable","request_id":"8997bda3-65c4-45c3-ab38-c909f905fc4d"}}

data: [DONE]

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"upstream service unavailable after retries; please retry","request_id":"8997bda3-65c4-45c3-ab38-c909f905fc4d"}}

data: [DONE]

event: response.failed
data: {"type":"response.failed","response":{"id":"resp_8997bda3-65c4-45c3-ab38-c909f905fc4d","object":"response","status":"failed","output":[],"error":{"message":"upstream service unavailable after retries; please retry","type":"server_error","code":"upstream_unavailable"}}}

The message is a fixed string chosen from the failure classification — for example “upstream capacity exhausted after waiting; please retry” for a throttle, “upstream timed out before starting the stream; please retry” for a timeout, or a specific message for an exceeded context window. When actionable guidance applies (e.g. a model-selection steer), it is appended to the message, because a stream has no room for a separate hint field.

Detection examples

import json, httpx
 
payload = {
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "hi"}],
    "stream": True,
}
 
with httpx.stream(
    "POST", "https://api.nexotao.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-nexo-FAKE-EXAMPLE"},
    json=payload, timeout=None,
) as r:
    request_id = r.headers.get("x-request-id")
    r.raise_for_status()  # necessary, but NOT sufficient
 
    for line in r.iter_lines():
        if not line.startswith("data: "):
            continue
        data = line[6:]
        if data == "[DONE]":
            break
        chunk = json.loads(data)
        if "error" in chunk:                     # in-band failure
            err = chunk["error"]
            raise RuntimeError(
                f"{err.get('code')}: {err.get('message')} (request_id={request_id})"
            )
        # ... handle a normal chunk

const res = await fetch("https://api.nexotao.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-nexo-FAKE-EXAMPLE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    messages: [{ role: "user", content: "hi" }],
    stream: true,
  }),
})
 
const requestId = res.headers.get("x-request-id")
if (!res.ok) throw new Error(`HTTP ${res.status} (request_id=${requestId})`)
 
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader()
let buffer = ""
 
for (;;) {
  const { value, done } = await reader.read()
  if (done) break
  buffer += value
 
  let idx
  while ((idx = buffer.indexOf("\n\n")) !== -1) {
    const event = buffer.slice(0, idx)
    buffer = buffer.slice(idx + 2)
 
    const dataLine = event.split("\n").find((l) => l.startsWith("data: "))
    if (!dataLine) continue
    const data = dataLine.slice(6)
    if (data === "[DONE]") continue
 
    const chunk = JSON.parse(data)
    if (chunk.error) {
      throw new Error(
        `${chunk.error.code}: ${chunk.error.message} (request_id=${requestId})`,
      )
    }
    // ... handle a normal chunk
  }
}

Retry guidance

import json, random, time, httpx
 
NON_RETRYABLE_HTTP = {400, 401, 402, 403, 404, 405, 413}
 
def call_with_retry(client, url, headers, payload, max_attempts=5):
    delay = 1.0
    for attempt in range(max_attempts):
        r = client.post(url, headers=headers, json=payload)
        if r.status_code < 400:
            return r
 
        body = {}
        try:
            body = r.json()
        except json.JSONDecodeError:
            pass
 
        # The contract is `retryable`, not the HTTP status.
        if not body.get("retryable", r.status_code not in NON_RETRYABLE_HTTP):
            raise RuntimeError(
                f"{body.get('code')}: {body.get('error')} "
                f"(request_id={r.headers.get('x-request-id')})"
            )
 
        wait = delay
        if ra := r.headers.get("retry-after"):
            try:
                wait = max(wait, min(int(ra), 3600))
            except ValueError:
                pass
        time.sleep(wait + random.uniform(0, 0.5 * wait))   # jitter
        delay *= 2
 
    raise RuntimeError("attempts exhausted")

Cost and post-hoc debugging

Non-streaming responses carry the actual cost in headers:

On SSE (streaming) responses, X-Cost-Rp is deliberately omitted: headers must be written before the first byte, while the cost is only known once the stream ends.

So for a streaming call, the way to find out what it cost is:

Whichever route you use, the reconciled record contains the fields below. Two of them are worth knowing:

The record’s status tells you the final outcome, and in particular whether a failed request was charged at all:

Troubleshooting

401 auth.api_key_missing — the auth header never arrived. With curl, check your quoting and line continuations (\). With an SDK, make sure base_url/baseURL points at https://api.nexotao.com/v1 and that the key is actually set (not an empty environment variable).

401 auth.api_key_invalid — the key is not recognised. Most common causes: a stray space or newline got copied along, the key belongs to a different environment, or it was deleted. Create a new key in the dashboard. See Authentication.

402 billing.insufficient_balance — the balance cannot cover the estimated input plus a minimal answer. Nexotao checks this before calling a model, so a rejected request costs nothing. Top up in the dashboard; see Billing & Pricing.

429 rate_limit.rpm_exceeded / rate_limit.tpm_exceeded — the key’s per-minute limit was exceeded. Lower concurrency, apply backoff, or shrink the prompt/max_tokens. The X-RateLimit-* headers show the remaining quota and seconds until the window rolls over.

429 quota.key_limit_exceeded — the key’s spending limit was reached. That is a budget cap you set yourself in the dashboard, not a rate throttle. Raise it or turn it off there.

400 model.unknown — the model id is misspelled or no longer active. Fetch the valid list:

curl -sS https://api.nexotao.com/v1/models \
  -H "Authorization: Bearer sk-nexo-FAKE-EXAMPLE"

404 route.not_found — the path is not served. The most frequent case is a generic OpenAI client calling /v1/images/generations or /v1/audio/transcriptions. Neither endpoint is available on Nexotao — see the served endpoint list in the API Reference.

A stream ends with no text and no error — this is almost always an in-band error your client did not parse. Revisit In-band streaming errors above, then look the request id up on the dashboard Usage page: a status of aborted_stream or upstream_error confirms the request failed and was not charged.

Still stuck? Collect the request_id, the code, and the time it happened, then contact support through the dashboard. Without a request_id, a single request is nearly impossible to find in the logs.