Errors and request identifiers

When LYRouter rejects a call, it returns a 4xx or 5xx status code. On OpenAI-compatible endpoints the error body is {"error": {"message", "type", "code"}}; on /v1/messages it is converted to the Anthropic format; a few responses are an HTML page or a single line of plain text. Look up the status code and the exact error.message in the quick reference on this page to tell whether the problem lies in the request itself, in the account and configuration, or with the platform or the upstream provider, and what to do about it. The gateway does not return a request ID in response headers. To pin down a specific call, open the request's detail in Log analysis and copy the Request ID at the top.

Error response format

OpenAI-compatible format

Apart from /v1/messages, every endpoint (Chat Completions, Responses, Embeddings, images, video and others) returns this error body by default:

{
  "error": {
    "message": "insufficient credit balance",
    "type": "insufficient_quota",
    "code": "insufficient_credit_balance"
  }
}

Anthropic format (/v1/messages)

When you call through /v1/messages, both the gateway's own errors and upstream errors are converted to the Anthropic format, with message unchanged:

{
  "type": "error",
  "error": { "type": "authentication_error", "message": "invalid api key" }
}

After conversion, error.code and the additional fields (such as limit and retry_after) are dropped; response headers are kept as usual. The error messages on this page apply to /v1/messages too. When you need to tell specific causes apart, go by the status code plus message, or look up the request in the logs.

The 404 → not_found_error mapping above does not apply to a 404 for a path or HTTP method that does not exist: calling /v1/messages with GET, for example, returns 404 {"error_msg":"404 Route Not Found"}, which is not converted to the Anthropic format.

Responses that are not JSON error bodies

For a plain-text 400 returned by the gateway, the Content-Type response header is currently still application/json, so parsing it directly as JSON fails, and some SDKs report an error such as "unable to parse the response". A safe approach is to check the status code first, then check whether the body is JSON (try to parse it); if it parses, read error.message, message and error_msg in that order; if none is present, log the first few hundred characters of the raw response:

# -i also prints the status line and response headers (such as Retry-After and x-aigw-quota-*)
curl -sS -i https://api.lyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"Hello"}]}'

import os
import requests  # install it first with pip install requests; the OpenAI SDK does not include it

resp = requests.post(
    "https://api.lyrouter.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    json={"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello"}]},
    timeout=400,  # longer than the gateway's 6-minute wait for the upstream
)
if resp.status_code >= 400:
    try:
        body = resp.json()
    except ValueError:  # HTML error page or plain text
        body = {}
    err = body.get("error", body) if isinstance(body, dict) else {}
    message = err.get("message") or err.get("error_msg") or resp.text[:300]
    print(resp.status_code, err.get("code"), message)

const resp = await fetch("https://api.lyrouter.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "MODEL_ID", messages: [{ role: "user", content: "Hello" }] }),
});
if (!resp.ok) {
  const text = await resp.text();
  let err = {};
  try {
    const body = JSON.parse(text);
    err = body.error ?? body;
  } catch {
    // HTML error page or plain text
  }
  console.log(resp.status, err.code, err.message ?? err.error_msg ?? text.slice(0, 300));
}

Quick reference

In the Who handles it column, "administrator" means the current Account Owner or a workspace Admin, and "Contact support" means the platform needs to act.

400: request format or parameters

The gateway returns every 400 in this section before sending the request to the upstream.

Model field and request body

When a default model is set, a chat request without model is answered by the default model instead, and you do not get missing_model. Setting the default model is covered in Channels and routing.

Content-Type and multipart (plain-text responses)

Model does not support the endpoint or input

type is invalid_request_error; tell them apart by error.code:

Fix: check the endpoints and input types a model supports in Model marketplace, and switch to a model that supports them; see Capabilities and compatibility.

Unsupported or invalid parameters

unsupported parameters for this model: <parameter> (unsupported_parameters): the request carries X-Gateway-Strict-Parameters: true and contains parameters the selected model does not support. Without this request header, the gateway drops those parameters, makes the call as usual and lists their names in the X-Gateway-Unsupported-Parameters response header. Both headers currently cover only image and video endpoints; parameters that chat endpoints drop during cross-protocol conversion (such as response_format, seed and n) neither trigger this error nor appear in this response header; see Gateway headers and extensions. Fix: remove the parameters listed in the error, or switch to a model that supports them.

invalid_parameter: error.message states directly which parameter is wrong and how. Common ones:

Value ranges for each parameter are in Multimodal capabilities.

Native passthrough not available

Message: native passthrough was required by `x-gateway-passthrough: require` but is not available for this request (<reason>)

A request with x-gateway-passthrough: require means "the request body must be sent as is to an Anthropic-protocol upstream, with no conversion". When the gateway cannot do that, it rejects the request outright instead of quietly converting it; falling back to a channel that does not use the Anthropic protocol also ends with this error. On /v1/messages this error is returned in the Anthropic format, with message identical to the message above: {"type":"error","error":{"type":"invalid_request_error","message":"native passthrough …"}}; on other endpoints it is a single line of plain text. The parentheses give the reason for the refusal:

/v1/messages currently does not have request-side native passthrough enabled, so requests carrying this header are rejected with route_disabled. Remove the header (or change it to prefer) and the request goes through the normal protocol conversion path; see Anthropic Messages.

401: authentication failed

A 401 request cannot be attributed to any workspace and does not appear in the logs. Detailed troubleshooting for each cause is in 401 / 403: authentication and access.

402: insufficient balance or expired subscription

type is insufficient_quota. The balance check happens before the call: as long as the balance is above 0, a call can start, and one call can push the balance below zero; only the calls after that are rejected. When the balance is insufficient, the gateway does not switch to another channel or billing method. Billing rules are in Billing and Credits.

403: access denied

API key and source

Permanent-ban responses carry the response header X-RateLimit-Reason: api_key_permanently_banned, and the rejected requests are not written to the logs.

Model not enabled

Model is not available in the model plaza (model_not_available, type is access_denied): in the Model marketplace of the key's workspace, every provider of this model is not enabled.

• An administrator enables the model in Model marketplace, or the caller switches to an enabled model.
• Using @vmodel/<name> or lyrouter/auto on image or video endpoints also returns this error: those endpoints accept only a concrete model ID.
• When the workspace has a default model set, a chat request for a model that is not enabled is usually answered by the default model instead; you can confirm this in Model (actual) in the logs. See Unavailable models.

Guardrails

Request blocked by guardrail policy (type is guardrail_blocked): the request matched a blocking policy in the workspace's guardrails and was not sent to the model. The message does not include the policy name or the matched content; use error.code to tell the policy type:

• Response blocked by guardrail policy (guardrail_sensitive): the answer to a non-streaming request matched a sensitive-data policy. The upstream had already generated the answer, so the call is billed as usual. A streaming request that has already started output is not interrupted; the matched content is masked in the output.
• Subject is blocked by an active security ban (guardrail_subject_banned): an intent security policy has its action set to ban, so the key that triggered it is banned, and every request is refused during the ban. The ban lifts at the automatic unban time set in the policy, or earlier when an administrator lifts it in Security events.

Retrying the same request gives the same result. The caller can change the request content or switch to an allowed model; administrators check match details in Security events and adjust policies in Guardrails; see Guardrails and semantic auditing.

404 / 409: path or resource not found

previous_response_id in POST /v1/responses is validated by the upstream provider, and an invalid one returns the upstream's error; see Responses. When a video task itself fails, the query endpoint returns HTTP 200, with the task object's status set to failed and error.code set to deadline_exceeded (timed out; the query endpoint may not show it at present, see Asynchronous tasks), canceled (canceled) or the error code given by the upstream (upstream_error by default), sometimes with the upstream's request ID in error.provider_request_id; see Asynchronous tasks.

429: rate limits, circuit breaking and upstream limits

• Quota fields: <subject> is apikey, member, dept or ws; <metric> is requests, total_tokens, prompt_tokens, completion_tokens or credits; <window> is minute, minutes, day, month or total (cumulative, never resets). Windows are aligned to Beijing time, and usage is counted only after a request completes.
• Response headers: when quotas are configured, responses to calls that go through gateway routing and the quota check (chat, embeddings and the like; both successful responses and quota 429s) carry x-aigw-quota-<metric>-limit / -remaining / -reset, where the metric is credits, tokens, requests, input-tokens or output-tokens; /v1/messages also carries anthropic-ratelimit-*, but credits have no matching header, so when only Credits quotas are configured the gateway does not generate anthropic-ratelimit-*.
• Retry-After: set only by the circuit breaker (api_key_circuit_open), together with X-RateLimit-Reason: api_key_circuit_open and X-RateLimit-Reset (Unix seconds); quota 429s do not carry it. The upstream's own Retry-After is forwarded only on /v1/messages.
• Circuit-breaker steps: 30 seconds the 1st time, 2 minutes the 2nd, 10 minutes the 3rd, 12 hours the 4th, and a permanent ban the 5th; trips accumulate over the key's whole lifetime. 402, 403 and 429 responses returned by the gateway also count as failures; circuit-broken requests are not written to the logs.

Full details are in 429: rate limits and quotas and Budgets, quotas and rate limits.

500 / 504: upstream connection failed or timed out

• The gateway's read timeout for the upstream is 6 minutes. For streaming requests it is measured between two consecutive pieces of output, so the request does not time out as long as output keeps coming.
• Before returning, the gateway has already tried other channels under the rules in Retries and fallback, and returns only after every candidate has failed. Once a streaming request has started output, the gateway no longer switches channels; see "Error events during streaming" below.
• Fix: retry with capped exponential backoff; use stream: true when generating very long content; check the upstream time in Latency breakdown in the logs. See Timeouts and interrupted streams.

Configuration 500s (JSON error body)

The following 500s carry a JSON error body (type is api_error). They mean a platform-side problem with the channel or format-conversion configuration that has nothing to do with the request content, so retrying usually does not help. Note the Request ID and contact support, and switch to another model:

503: no available channel, or billing or configuration temporarily unavailable

billing balance is temporarily unavailable has type billing_unavailable; use error.code to tell whether it can recover on its own:

Official SDKs such as OpenAI's and Anthropic's retry 503 automatically by default, but no_route_candidate, billing_maintenance and supplier_cost_snapshot_not_ready do not recover unless the request or configuration changes.

Errors returned by the upstream provider

The gateway forwards the error status code and response body returned by the upstream provider to you as is, and the source in the Status explanation column of the logs shows Upstream.

• Channels are tried first: when the upstream returns an error or the connection fails, the gateway retries on the same model's other channels according to the workspace's routing strategy; when all of them fail, you receive the upstream error of the last attempt. When a default model is set, a chat request may also be answered by the default model instead; see Retries and fallback.
• Upstream 401 / 403: usually means the upstream rejected the credential. With BYOK, confirm with the provider that the API key is valid and has enough quota, then test the connection again in BYOK.
• /v1/messages: upstream errors are converted to the Anthropic format as well.

Upstream returns an empty response body

When the upstream returns only an error status code with no response body, the gateway fills in an error body and marks it with generated_by: "ai-gateway" as generated by the gateway:

{
  "error": {
    "message": "upstream <provider> returned HTTP 429 for POST <path> with an empty response body",
    "type": "rate_limit_error",
    "code": "upstream_rate_limited",
    "upstream_status": 429,
    "generated_by": "ai-gateway"
  }
}

When the upstream includes its own request ID in the response headers, the error body also has an upstream_request_id; use it when you report the issue to the provider.

Upstream declares an error in a successful response

A few upstreams return HTTP 2xx but declare a failure in the response body, mostly for image and video generation. The gateway rewrites this into an error response: the status code comes from the error the upstream declared, error.code is upstream_rejected (the upstream rejected the request) or upstream_no_artifact (the upstream produced no image or video; carries upstream_finish_reason), and upstream_status is the upstream's original 2xx status code. These errors are not retried on other channels; adjust the request content according to error.message.

Error events during streaming

All the gateway rejections listed above happen before output starts, so a stream: true request also receives an ordinary error response with the matching status code, not an SSE event.

After streaming output has started (the status code is already 200), if the upstream breaks off or times out, the gateway no longer switches channels. Instead, it appends an error event at the end of the stream and then closes the connection:

OpenAI-compatible endpoints (Chat Completions, Responses and others):

data: {"error": {"message": "upstream timed out after the response had started", "type": "api_error", "code": "stream_interrupted"}}

Anthropic Messages (/v1/messages):

event: error
data: {"type": "error", "error": {"type": "api_error", "message": "upstream timed out after the response had started"}}

• On a timeout, message is upstream timed out after the response had started; on a connection or read failure, it is upstream failed after the response had started.
• Error events that the upstream itself sends in the stream (such as Anthropic's overloaded_error) are passed on to you in the protocol you called. The official OpenAI and Anthropic SDKs raise an API error when they receive either kind of error event.
• After an error event, no end marker follows (data: [DONE], message_stop, response.completed). Treat "no end marker received" as a failed call, and do not treat the partial output you received as a complete result.

Event structures for each protocol are in Streaming; advice on retries and deduplication is in Timeouts and interrupted streams.

Which errors can be retried

Never retry a 4xx automatically without a delay: 402, 403 and 429 responses returned by the gateway all count toward the error-rate circuit breaker, so a program that keeps failing soon gets its key circuit-broken, and the 5th trip is a permanent ban.

Request identifiers

The gateway does not return a request ID

LYRouter does not return a request ID in response headers. The id in the response body (such as chatcmpl-..., msg_... or resp_...) is the ID of the protocol object, and you cannot search the logs by it. To pin down a call, record the call time, endpoint path, model and API key name on the client, then find the request in the logs.

Get the Request ID from the log detail

1. Open Log analysis in the workspace's left menu. Logs are searchable within a few seconds after a call ends.
2. Filter by Time, API Key, Model, Status and other conditions. Time in the list is when the request finished.
3. Click the row to open Log detail; the value after Request ID at the top identifies this request. Select it and copy it.

You can paste the Request ID into the log search box to find this log again. Account Members see only logs produced by API keys they created. These requests cannot be found in the logs: 401s, 404s for a path that does not exist, requests rejected by the error-rate circuit breaker (429 api_key_circuit_open) or by a permanent ban (403 api_key_permanently_banned), and GET /v1/models. For these, provide the call time, endpoint path and full error message. Full use of the logs is covered in Troubleshooting with logs.

Other identifiers in the logs

What to include when reporting a problem

Redact before sending:

• Do not send the API key in plaintext, the full Authorization or x-api-key request header, or the BYOK keys you hold with providers.
• Delete or replace personal information and business data in prompts, answers and uploaded files; when a minimal reproduction can show the problem, do not attach the original content.
• Content copied from Raw packets in the logs excludes credential headers, but the body may contain sensitive information; check it before sending.