Errors

UberLLM returns OpenAI-style error envelopes so existing error handling works unchanged:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low to serve this request.",
    "type": "insufficient_credits"
  }
}

Inference surface (`/v1/*`)

HTTP	`code`	Meaning	What to do
402	`insufficient_credits`	Your prepaid balance can't cover the request's reservation.	Top up at Dashboard → Credits.
402	`key_spend_cap_exceeded`	This key hit its configured spend limit (daily / monthly / lifetime).	Raise or remove the key's cap, or use another key.
404	`unknown_model`	The `model` id isn't in the catalog.	Check `GET /v1/models`; fix the id.
429	`rate_limited`	This key exceeded its per-minute request limit, or an upstream rate-limited us and no fallback was available.	Back off and retry with jitter; raise the key's rate limit.
502	`no_available_provider`	Every candidate provider failed before returning any content (after failover).	Retry shortly; the deprioritized providers recover automatically. Any reservation was fully released.

Reservations and aborts

UberLLM reserves an estimated cost before proxying and settles from actual usage afterward. If a request errors, aborts, or you disconnect mid-stream, the unused reservation is released — you are only billed for content actually produced. Aborted streams are reconciled from a tokenizer estimate and flagged in Dashboard → Activity.

Rate limiting

Per-key rate limits are enforced with a fixed window. On the inference surface, rate-limit checks fail closed — if UberLLM cannot verify your limit, the request is rejected rather than served unmetered. Set (or raise) a key's rate_limit_per_min when you create it.

Seller API (`/api/v1/seller/*`)

These use standard REST codes:

HTTP	`code`	Meaning
400	`invalid_request`	Validation failed (e.g. non-https `endpoint_url`, missing prices for `absolute`, `multiplier` outside `0 < m ≤ 1.5`). The message names the field.
400	`model_not_in_catalog`	`model_id` isn't a known catalog model.
401	`unauthorized`	Missing or invalid dashboard JWT.
404	`seller_not_found`	No seller for your org — call `POST /api/v1/seller/register` first.
404	`offer_not_found`	No offer with that id under your seller.
409	`invalid_status_transition`	Illegal status change — e.g. resuming a `delisted` offer (delisted is terminal).

Note: a failed validation probe is not an error response. The offer is created/updated successfully and returned with status: "paused" and a last_probe_error explaining why — fix the endpoint and PATCH it back to active to re-probe. See Sellers.

Auth errors

HTTP	Meaning
401	Missing/invalid `Authorization` header. Inference keys are `Bearer ull_...`; dashboard endpoints use your account JWT.
403	The key is valid but lacks the required scope (e.g. an inference-only key calling a dashboard endpoint).