Errors

The API returns standard HTTP status codes with OpenAI-style error bodies, so most existing OpenAI-compatible client libraries can parse them without changes. Every error response has the same shape:

{
  "error": {
    "message": "Human-readable description of what went wrong.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

string

A human-readable description of the problem. Safe to log and surface to developers, but do not parse it programmatically; parse type and code instead.

string

The high-level error category. One of invalid_request_error, insufficient_quota, permission_error, rate_limit_error, api_error, or upstream_error.

string

The specific machine-readable error: invalid_api_key, insufficient_balance, upgrade_required, insufficient_scope, insufficient_permissions, model_not_found, dedicated_endpoint_not_found, unknown_provider, and on the management API also not_found, precondition_failed, logging_disabled and a few endpoint-specific codes. Branch on this value in your error handling.

string

Present only on insufficient_scope: the scope the call needed.

Status codes

Status	Meaning	What to do
`200`	Success.	—
`400`	Bad request: malformed body, unsupported parameter, or unknown provider prefix.	Check your request shape and provider prefix.
`401`	Unauthorized: missing, malformed, or revoked API key.	Verify your key and `Authorization` header.
`402`	`insufficient_balance`: the wallet can’t cover the request’s worst-case hold. `upgrade_required`: the workspace’s plan doesn’t include the action.	Top up or enable auto-reload; or upgrade the plan.
`403`	Forbidden: the key lacks the scope the call needs (`insufficient_scope`), or the person who minted it lacks the role (`insufficient_permissions`).	Mint a key with the right scope, from an owner/admin account where the endpoint needs one.
`404`	Model or dedicated endpoint not found.	The model isn’t in the priced catalog, or the routing key is wrong.
`408`	Request timed out.	Retry with backoff; check for very large requests.
`429`	Rate limited.	Back off and retry; see Rate limits.
`502`	Upstream error.	Transient provider issue; retry with backoff.

Error codes

The type and code fields pinpoint the exact failure. Use the table to map a code to its category, HTTP status, and remedy.

`code`	`type`	Status	Meaning
`invalid_api_key`	`invalid_request_error`	`401`	Key is missing, malformed, or revoked.
`insufficient_balance`	`insufficient_quota`	`402`	Wallet can’t cover the request’s worst-case hold.
`upgrade_required`	`insufficient_quota`	`402`	The workspace’s plan doesn’t include this action; the message names the plan that does.
`insufficient_scope`	`permission_error`	`403`	The API key was minted without the scope this call needs; `required_scope` names it.
`insufficient_permissions`	`invalid_request_error`	`403`	The user who minted the key isn’t a workspace owner/admin, and the endpoint requires one.
`model_not_found`	`invalid_request_error`	`404`	Model isn’t in the priced catalog.
`dedicated_endpoint_not_found`	`invalid_request_error`	`404`	Dedicated routing key isn’t owned by your workspace, or was deleted.
`unknown_provider`	`invalid_request_error`	`400`	Provider prefix has no configured key.
—	`upstream_error`	`502`	Transient error reaching the model provider.

invalid_api_key (401)

The key is missing, malformed, or revoked. Keys are sent as Authorization: Bearer <key>. Confirm the header is present and the key is active in your workspace. Rotating a key immediately invalidates the old one, so deployments still holding a stale key will see this error.

insufficient_balance (402)

Before a request runs, errorbar places a hold on your wallet for the request’s worst-case cost, enough to cover the maximum tokens it could produce. If the wallet can’t cover that hold, the request is rejected with 402 before any provider is called. You’re never charged for a request that returns 402. Add funds or turn on auto-reload to avoid interruptions. Capping max_tokens also lowers the hold, since the worst case shrinks.

upgrade_required (402)

The request was well-formed and the key was allowed to make it, but the workspace’s plan doesn’t include acting on it. The management API raises this when a PUT /v1/aliases sets a canary percentage above 0 or gate_mode: "auto" on a plan without partial rollouts or gate enforcement, and when POST /v1/dedicated creates an endpoint on a plan without dedicated capacity. The message always starts with Upgrade to <Plan> and names the plan that includes the action; nothing is charged. Not retryable: change the plan or the request.

insufficient_scope (403)

The key exists and is valid, but it was minted without the scope this call needs. The body’s required_scope names it (evals:write, aliases:write, or platform:write; reads are never refused this way, since every scoped key can read). Mint a key with that scope from the dashboard’s API keys page, or use a key created with full access. Keys minted before scopes existed are never refused this way. See Key scopes.

insufficient_permissions (403)

A key acts as the user who minted it. Endpoints that spend money or redirect traffic require that user to be a workspace owner or admin; this is the refusal when they aren’t. Mint the key from an owner/admin account. See Key permissions and roles.

model_not_found (404)

The model you requested isn’t in the priced catalog: either the id is misspelled or the model isn’t offered. This is a deliberate 404: errorbar refuses to run a model it can’t price so you’re never billed for an unpriced model. Call /v1/models to list valid ids.

dedicated_endpoint_not_found (404)

You addressed a dedicated endpoint as dedicated/<routing-key>, but that routing key either isn’t owned by your workspace or has been deleted. Check the routing key on the endpoint’s page in the dashboard, and confirm the endpoint still exists. See Dedicated endpoints.

unknown_provider (400)

You used a provider prefix that has no configured key. Verify the provider prefix is spelled correctly and that a key for that provider is configured for your workspace.

upstream_error (502)

A transient error reaching the model provider. Retry with exponential backoff. The message includes a request id reference; quote it if you contact support.

Retrying safely

Retry 429, 408, and 502 responses with exponential backoff and jitter.

Completions are safe to retry: you’re only billed for tokens actually produced. A retried request that never returned tokens costs nothing.

For a 502, the message includes a request id reference. Quote that reference if you contact support so the request can be traced.

Don’t blindly retry 4xx errors other than 408 and 429. A 400, 401, 402, 403, or 404 means the request, the key, or the plan needs to change; retrying it unchanged will fail the same way every time.

Python

This helper retries only the transient statuses and backs off exponentially with jitter:

import time
import random
import httpx

RETRYABLE = {408, 429, 502}

def call_with_retry(client, payload, retries=5):
    for attempt in range(retries):
        resp = client.post("/v1/chat/completions", json=payload)
        if resp.status_code == 200:
            return resp.json()

        if resp.status_code not in RETRYABLE or attempt == retries - 1:
            # Non-retryable, or out of attempts: raise with the parsed error.
            err = resp.json().get("error", {})
            raise RuntimeError(
                f"{resp.status_code} {err.get('code')}: {err.get('message')}"
            )

        # Exponential backoff capped at 30s, plus jitter to avoid stampedes.
        sleep = min(30, 2 ** attempt) + random.random()
        time.sleep(sleep)

curl

curl --retry with backoff covers the transient cases for simple scripts:

curl https://gateway.errorbar.ai/v1/chat/completions \
  -H "Authorization: Bearer $ERRORBAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen3-32B", "messages": [{"role": "user", "content": "Hi"}]}' \
  --retry 5 \
  --retry-delay 1 \
  --retry-all-errors

Inspecting errors after the fact

Every failed request appears in the dashboard’s request log, and the Errors by cause breakdown groups failures by category (rate limits, timeouts, upstream errors). See Observability to diagnose patterns across many requests rather than one at a time.

Get started

Capture

Observe

Grade & Judge

Evaluate

Improve

Run at scale

Platform

Status codes

Error codes

Retrying safely

Python

curl

Inspecting errors after the fact

​Status codes

​Error codes

​Retrying safely

​Python

​curl

​Inspecting errors after the fact

Status codes

Error codes

Retrying safely

Python

curl

Inspecting errors after the fact