Errors

An error response has a JSON body. Match on error.code, not on the message. The status tells you what kind of fix to make.

What to do

When the auction refuses a request, eligibility.excluded lists each offer that it left out and why. See Exclusion reasons.

Error format

{
  "error": {
    "message": "`reasoning.effort` is not supported by any offer for kimi-k3",
    "type": "liquid_error",
    "code": "unsupported_parameter",
    "param": "reasoning.effort",
    "eligibility": { "excluded": [ … ] }
  }
}

A 502 or 504 with an HTML body comes from the network in front of the exchange, not from the exchange.

POST /v1/messages returns the Anthropic format, {"type": "error", "error": {"type": ..., "message": ...}}. An auction error keeps the code, param, eligibility, auto, binding_rule and provider fields next to type and message.

Error codes

Authentication

Request

unsupported_parameter also applies to these cases:

• A control that no offer declared. param is the feature name: image.seed, image.background, image.output_compression, image.stream, video.seed, video.creativity, video.upscale_factor, video.continue, speech.instructions, speech.turns, transcription.diarize, transcription.keyterms or embedding.input_type. The message reads "image.seed is not supported by any offer for ". The exchange holds nothing.
• A reference input that no offer reads. param is input.image, input.audio, input.video or input.file.
• An output option that no offer serves on an image, speech, video or embedding request. param is n, size, output_format, voice, response_format, seconds or dimensions. /v1/models lists image_sizes for an image model.
• On /v1/responses: a hosted tool other than web_search, previous_response_id, conversation and background: true. The exchange stores no responses.
• On /v1/messages: a hosted tool such as web_search, web_fetch or code_execution. A tool that your client runs is allowed.
• A provider setting that the exchange cannot apply. See Move from OpenRouter.

Models and strategy

These codes come before the auction.

Auction

The price cap is the most that a job can cost. The exchange sets it before the first token.

If an unserved parameter is the only reason for every exclusion, the error is 400 unsupported_parameter.

When a provider fails

If the awarded provider fails before any output, the exchange releases the hold and tries the next offer.

• If no offer takes the job, you receive provider_failed. The exchange keeps that offer out of the ranking for a while.
• If no other seller has the model, the first request 30 seconds after the failure is a trial on that offer. Until then, and during the trial, requests get model_unavailable. Each failed trial doubles the wait, up to 7.5 minutes.

After any output, or if the provider may still run the job, the exchange tries no other offer. You get one cap and one charge.

When an allowlist leaves no offer

An offer can serve the model while a provider allowlist matches none of the providers. The no_eligible_offer error then has error.binding_rule.

• message names the providers and the model. For allowed_providers, it also suggests exchange.candidates.providers.prefer.
• The exchange ranks the request again without the allowlist. If an offer can then win, message names its providers and the lowest estimate for the job, and fixes has the same data in admits and estimate_nanos.
• The status is 400 for allowed_providers and 403 for the allowlist of a key or a guardrail. retryable is false.
• If the quotes of an allowed provider expired, the status is 503.

Auto

These codes refuse a request that Auto ranks. See Auto Router.

A no_eligible_offer error for an Auto request also has error.auto: the decision that Auto made before the rules left no offer.

Ranking axis

A model-name suffix (smartest, fastest or cheapest) or a smartest strategy can return these codes. See Axis routing. smartest is Auto mode version 4, so it can also return the Auto codes.

Provider endpoints

A buyer key does not reach these seller endpoints.

Reservations

You get these codes when a preset names a reservation. See Reservations.

Exchange

Fixes

Each entry in fixes is one change. reason is the exclusion reason, offers is the count of offers it left out, and message says what to change. The message of the error holds the same text, because many clients show only that field.

The exchange tests each change before it answers. It drops the one rule and ranks the request again. admits lists the providers that can then win. estimate_nanos is the lowest charge, in nano-USD (one USD is 1,000,000,000), that you can expect for this job at one of them. The charge at settlement follows the tokens that the job uses.

owner says who can make the change. A field of the request cannot widen a rule of a key preset or a guardrail.

owner is absent when the state of the market caused the reason.

Exclusion reasons

Each entry in eligibility.excluded has provider, offer_id, reason and sometimes detail. The tables group the reasons by what you change.

Change the model or the provider

• job_kind_not_served: the offer makes a different output, such as an image offer for a chat job.
• model_not_served: the offer does not serve the requested model.
• model_not_allowed: excluded by exchange.candidates.models.exclude, or outside the preset of the API key.
• provider_not_allowed: excluded by exchange.candidates.providers.allow.
• vendor_not_allowed: excluded by exchange.candidates.creators.allow.
• provider_blocked: excluded by exchange.candidates.providers.exclude.
• pinned_offer_not_resting: the pinned offer is not on the book.

Change a price limit

• cap_exceeds_buyer_cap: the worst-case charge is more than cap_usd. Raise cap_usd, or lower max_tokens.
• cap_exceeds_budget: the worst-case charge is more than the balance or the key limit. Add funds, raise the limit, or lower max_tokens.
• rate_above_ceiling: a rate is more than exchange.limits.price.input_usd_per_mtok, exchange.limits.price.output_usd_per_mtok, exchange.limits.price.cache_read_usd_per_mtok or exchange.limits.price.cache_write_usd_per_mtok.
• above_cost_tier: the price is above the requested exchange.rank.cost_tier.

Change a speed limit

• service_too_slow: the deadlines of the offer are longer than exchange.limits.ttft_ms or exchange.limits.completion_ms.
• throughput_too_low: the offer gives fewer tokens each second than exchange.limits.min_tps.

Change the request itself

• feature_unsupported: the offer does not support a parameter of the request. detail names it.
• media_unsupported: the offer does not accept the attachment in the form sent. detail names the constraint, such as image.max_bytes.
• context_too_large: the input and max_tokens together exceed the context window of the offer. See Output limits.
• output_bound_unsupported: max_tokens is outside the output limit of the offer. On a text job, detail gives the request and the range, such as asked 200000, accepts 1 to 8192. On an image, speech, video or embedding job, detail names the parameter that the deployment does not serve. See Output limits.

Change a data rule

• region_policy: excluded by exchange.privacy.regions.
• retention_policy: the offer cannot meet the requested exchange.privacy.retention.
• workload_profile_not_targeted: the offer does not target the requested exchange.rank.workload_profile.

Nothing to change

• offer_expired: the offer expired before the auction ran. Send the request again.
• superseded_by_own_offer: the same provider had an eligible offer that ranked ahead of this one.

Auto has no score

• score_unmapped: Auto has no score for the deployment at the reasoning setting of the request.
• score_missing: the deployment has no score for the task Auto ranked by. detail names the score field.

Output limits

max_tokens is a maximum for the answer. If every offer is excluded, and output_bound_unsupported or context_too_large excluded at least one, the auction runs again. It tries a lower max_tokens for each of those offers, from the largest value to the smallest.

• output_bound_unsupported: the lower value is the output limit of the offer.
• context_too_large: the lower value is the room that the input leaves in the context window, and not more than the output limit.
• An offer gives no value if the room is less than 1,024 tokens, or if another reason excluded it.
• The auction keeps the first value that an offer accepts.

The exchange calculates the cap from the lower value. An answer that reaches it stops with finish_reason: "length" (stop_reason: "max_tokens" on the Anthropic endpoint).

A request with no limit (max_tokens, max_completion_tokens or max_output_tokens) starts at 32,768 tokens. If the cap or your balance excludes all offers, the exchange halves that limit until an offer fits, down to 1,024 tokens. It never changes a limit that you set.

• If your limit does not fit your balance, the response is 402 insufficient_balance. needed_usd is the lowest cap for your limit.
• If your limit does not fit your cap, the response is 400 no_eligible_offer with param set to exchange.cap_usd.
• The exchange never lowers max_tokens to or below a thinking budget. It refuses such a request with no_eligible_offer.

Reasoning models

The thinking of a reasoning model counts toward max_tokens, and the exchange bills it as output.

• On POST /v1/chat/completions, the thinking arrives as reasoning, on each streamed delta or on the message.
• usage.completion_tokens_details.reasoning_tokens and exchange.reasoning_tokens give the tokens that the thinking used.
• A model that thinks until the limit stops with finish_reason: "length" and an empty content. You pay for the thinking. Use a larger max_tokens.
• A model that stops after its thinking with no text and no tool call gives you nothing to use. The job fails, you pay nothing, and the receipt records empty_response.
• On POST /v1/messages, the response has thinking blocks only if thinking is not disabled. Without it, a small max_tokens can end with no text.

Tool calls

If the request sends tools, the exchange checks each tool call in the answer. A call is bad when it has one of these faults:

The receipt has the counts in answer_checks.tool_calls, answer_checks.tool_call_errors and answer_checks.tool_call_faults.

• Not streamed. The exchange reads the whole answer first. If a call is bad, it drops the answer and sends the job to the next offer. If no offer is left, the job fails with invalid_tool_call.
• Streamed. The exchange counts the bad calls and keeps the answer.

Tool-call markup. Some providers do not turn the calls of a model into tool_calls, and your agent loop stops. The exchange sets answer_checks.tool_markup to 1 when the request sent tools, the answer has no tool call, and the text holds DeepSeek, Hermes, Qwen or Kimi markup. It keeps the answer and records the markup for the deployment.

Structured output

If you send response_format with json_object or json_schema, the exchange checks the answer when the job ends. json_object asks for one JSON value. json_schema also asks that the value matches your schema. On POST /v1/messages it checks output_config.format, and on POST /v1/responses it checks text.format.

The result is in exchange.answer_checks.structured_output, on the last chunk of a stream.

• Not streamed. For not_json or schema_mismatch, the exchange drops the answer and sends the job to the next offer. If no offer is left, the job fails with no charge, and the receipt records invalid_structured_output.
• Streamed. You receive the answer as the provider sent it, and you pay for it.

Only not_json and schema_mismatch count against the provider.

If the answer writes more than 1,024 whitespace characters in a row outside a JSON string, the exchange stops it and counts it against the provider. A request that is not streamed goes to the next offer. A stream fails with provider_failed, and you pay nothing.

The receipt keeps the result and the keyword, not the path of the failed field.