Errors

Every error, on every endpoint, uses one JSON envelope:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "rate_limit_error",
    "code": "daily_limit_reached"
  }
}

Branch on code (stable, machine-oriented); show message to humans. 429 responses carry a retry-after header (seconds).

Absence of retry-after is meaningful. We send it only when waiting actually helps. A 503 provider_unavailable_billing has noretry-after because no amount of waiting fixes it — it clears when we top the provider account up. Treat a retryable failure and an unrecoverable one differently rather than backing off blindly into both.

One caveat worth knowing: no_route is emitted at three statuses (400, 404, 422). The code means the same thing each time — nothing was dialed — and the status tells you why the pool was empty. Branch on the status if you need to distinguish them; see the table below.

Empty-body 502/503/504 — the request never reached us

Everything on this page below describes an application error: the gateway ran, decided, and answered with the JSON envelope above. Occasionally you will instead get a5xx with an empty body. That did not come from the gateway. It came from the edge proxy in front of it, and it means your request was never processed.

The distinction is not cosmetic — branching on error.code gives youundefined, so code that switches on our codes falls through to its default branch and usually reports something misleading.

Detect it on the body, not the status. 502, 503 and 504 all appear as documented application codes too, so the status alone cannot tell you which kind you have. An empty body with no parseable error object is the reliable signal:

if (!res.ok) {
  const text = await res.text();
  if (!text) {
    // Edge/infrastructure: never reached the gateway. Retry with backoff.
    // Nothing was routed, so nothing was metered.
    throw new RetryableError(`gateway unreachable (HTTP ${res.status})`);
  }
  const { error } = JSON.parse(text);   // application error: branch on error.code
}

Where to look: status.bharatrouter.com, which is probed from outside our infrastructure and so keeps working when the gateway does not. Note that GET /health is not useful for this class of failure: if the edge cannot reach the gateway, it cannot serve /health either, so you will get the same empty 503 from the endpoint you are using to diagnose the empty 503.

All error codes

Inference (chat & embeddings)

Dashboard & account

Billing

BYOK

Routing, collections, endpoints & teams

The management endpoints share a small set of validation codes:

Edge 403 (Cloudflare error 1010) — not a BharatRouter error

A 403 with Cloudflare "error 1010" (an HTML body, not our JSON error shape) means the request was blocked at the edge WAF before reaching the gateway — it is triggered by bot-fighting rules on some default HTTP-client User-Agent strings (e.g. bare python-requests/python-urllib). It is not a rate limit and not an auth failure, though it is often misread as both. Fix: send a realUser-Agent header identifying your application (e.g. my-app/1.0) — the official OpenAI SDKs already do and are unaffected. If a legitimate integration still gets 1010, tell us and we'll allow-list its agent string.

Handling errors in code

With the OpenAI SDKs, BharatRouter errors surface as the SDK's standard exceptions — the envelope rides inside. A retry policy that covers everything above:

# Python
import time, openai

def chat(client, **kw):
    for attempt in range(4):
        try:
            return client.chat.completions.create(**kw)
        except openai.RateLimitError as e:        # 429: rate/daily/budget
            code = (getattr(e, "body", None) or {}).get("error", {}).get("code")
            if code in ("daily_limit_reached", "budget_exceeded"):
                raise                              # waiting seconds won't help
            time.sleep(2 ** attempt)
        except openai.APIStatusError as e:
            if e.status_code == 502:               # all_routes_failed
                time.sleep(2 ** attempt)           # circuits recover in ~30s
            else:
                raise                              # 400/401/402: fix, don't retry
    raise RuntimeError("retries exhausted")

// Node
try {
  await client.chat.completions.create({ model: "gemma-4-e4b-it", messages });
} catch (err) {
  const code = err?.error?.code ?? err?.code;
  if (code === "insufficient_credits") notifyOwnerToTopUp();
  else if (err.status === 429) scheduleRetry(err.headers?.["retry-after"]);
  else if (err.status === 502) scheduleRetry(30);   // all_routes_failed
  else throw err;
}

Rule of thumb: retry 429 (except daily_limit_reached /budget_exceeded) and 502 with backoff; never blind-retry 400/401/402 — they need a fix, not patience.