NewHow we catch a seller listing the wrong model, and refund you if one does.

Errors

MartLLM 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.
400 invalid_request The request body couldn't be parsed, or the model rejected the request (the message says why). Fix the request; it is not retried.
413 request_too_large The request body is over 10 MB (most often images sent as base64). Send images as https:// links, or shorten the conversation. Nothing was charged.
404 model_not_found The model id isn't available. A uberllm/ prefix in front is fine: uberllm/deepseek/deepseek-v4.1-flash reaches deepseek/deepseek-v4.1-flash. Check GET /v1/models; fix the id.
400 context_length_exceeded The prompt is longer than the model takes, whoever sells it. On /v1/chat/completions without a models list the closest model that takes it answers instead (the reply's model names it); this error comes when none does, or on /v1/messages. The message gives both sizes and names models that take it. Send less, or pick a model the message names. Nothing was charged.
400 tools_not_supported The request sends tools and the model cannot call them, whoever sells it. Same stand-in rule as above. The message names models that can. Send it without tools, or pick a model the message names. Nothing was charged.
400 max_price_exceeded Nobody sells the model within your provider.max_price right now (and no model in models could take it). Raise max_price, try later, or name other models. Nothing was charged.
400 unsupported_routing_option A provider option MartLLM cannot apply (the message names it). Leave it out; see Models & routing.
400 invalid_metadata metadata is not an object of up to 16 text values. Fix the tags; numbers go in quotes.
400 unknown_capability A best-price: / fastest: alias names no job. Use one of chat, image, image-edit, text-to-video, image-to-video, music, speech, transcription.
400 wrong_endpoint The model (or alias) does a job this route does not do: an image, video, music, speech or transcription model sent to /v1/chat/completions or /v1/messages, a chat model sent to a media route, or speech and transcription swapped. The message names the right route. Refused before anything runs; nothing is charged, and Activity lists it as refused. Send it to the route the message names (also in endpoints on /v1/models/{id}).
503 no_timing_data fastest: was asked before enough requests were timed to compare models. Use best-price: or name a model.
429 rate_limited This key exceeded its per-minute request limit, or the marketplace kept rate-limiting after automatic retries. Back off and retry with jitter; raise the key's rate limit.
503 no_available_provider Nobody can serve that model right now, even after automatic retries (no seller, every seller failing or too slow to start, or your provider options left nothing to route to), or a best-price: / fastest: alias found no model for the job that is available right now. The message names the model or the job. This also covers a seller whose own provider account failed: MartLLM tries other sellers, and never passes that seller's error on as if your key were wrong. Retry shortly or pick another model. Nothing was charged.
503 service_unavailable A temporary problem on MartLLM's side. Retry in a few minutes.

Image, video and music requests add a few codes of their own (image_required, invalid_image_url (a source picture link that does not lead to a picture), max_cost_too_low, idempotency_key_reused, artifact_expired); see Make a video or image.

A refused or failed chat request shows in Dashboard → Activity with the message you were sent. Chat, image, video, music, speech and transcription responses carry an X-Request-Id header with the same id as its Activity row, errors included.

Retries happen for you before an error is returned: up to 4 attempts, only before the first content byte. See Models & routing.

Reservations and aborts

MartLLM 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 MartLLM cannot verify your limit, the request is rejected rather than served unmetered. Set (or raise) a key's request limit per minute in Dashboard → API keys.

Every authenticated /v1/* answer carries the key's current window:

Header Meaning
X-RateLimit-Limit Requests this key may send per minute
X-RateLimit-Remaining Requests left in the current minute
X-RateLimit-Reset When the window starts over (Unix seconds)
Retry-After On a 429 from this limit: seconds to wait before retrying

Slow down when X-RateLimit-Remaining nears 0. The headers are left out when the window cannot be read.

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).