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