Error reference

Every failure response from the gateway model ingress (OpenAI / Anthropic / Gemini) uses a single error envelope: the body carries a stable reason identifier. HTTP status, error type, and whether a retry is allowed are decided by that reason in the kernel table at export time. This page is generated by lobsterpool/scripts/gen-error-reference.mjs from the LlmErrorReference component of the OpenAPI artifact. Do not hand-edit the table. After re-exporting the OpenAPI artifact, rerun the generator to update it.

Error bodies for the three protocols

The three protocols have different error-body shapes, but they carry the same reason (see the Anthropic / Gemini envelopes for those shapes; the examples below are the same failure rendered for each protocol):

OpenAI protocol — {"error": { … }}:

{
  "error": {
    "message": "上游服务暂时不可用，请稍后重试。",
    "type": "server_error",
    "param": null,
    "code": "upstream_server_error",
    "reason": "LLM_UPSTREAM_SERVER_ERROR",
    "request_id": "0197ffffffffffffffffffffffffffff"
  }
}

Anthropic protocol — {"type": "error", "error": { … }, "request_id": …}:

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "上游服务暂时不可用，请稍后重试。",
    "reason": "LLM_UPSTREAM_SERVER_ERROR"
  },
  "request_id": "0197ffffffffffffffffffffffffffff"
}

Gemini protocol — {"error": { … }}:

{
  "error": {
    "code": 502,
    "message": "上游服务暂时不可用，请稍后重试。",
    "status": "UNAVAILABLE",
    "details": []
  }
}

How to decide what to do

1. HTTP status: Look up reason in the table below. It is the same for all three protocols (the Gemini error body's code field matches the response HTTP status).
2. Whether to retry: Read response header x-should-retry. It matches the Retryable column below. When it is true, retry as that row says. When it is false, a retry will not change the result.
3. What the caller should do: Combine Owner with should_retry:
   • client → change the request;
   • upstream and retryable → retry later;
   • platformConfig → contact an administrator to check the model provider or routing configuration;
   • gatewaySelf → retry later when retryable, otherwise contact an administrator to investigate the gateway;
   • link → retry later when retryable, otherwise check network and gateway status;
   • reasons marked “By upstream evidence” or “By the deny detail code” assign the owner from evidence on that call. Investigate with the upstream status in the response.

The requested model is unavailable

The name the caller puts in the request is the model's call name. The gateway first resolves the call name, then checks whether the caller is allowed to use that model, and only then checks whether the model currently has a dispatchable upstream. The three results are not mixed:

• The model does not exist, or the caller is not allowed to use it (the caller's model group does not contain the model): both cases return the same response, 404 LLM_MODEL_NOT_AVAILABLE (OpenAI protocol code is model_not_found). The gateway does not distinguish “no such model” from “you cannot use this model”, so it does not expose the model catalog to an unauthorized caller. What to do: check the call name, or ask an administrator to add the model to a model group the caller can use.
• The model exists and the caller is allowed to use it, but there is no dispatchable upstream: returns 503 MODEL_NO_BACKEND (code is model_no_backend). Common causes are that every upstream of the model is disabled or deleted, or that a traffic-rule target has no upstream under this model. A retry will not change the result. An administrator must enable an upstream for the model or adjust the traffic rule.

Layered connectivity-failure classification (ConnectivityFailureKind)

Gateway data-plane, channel-root probes, model-provider tests, MCP discovery, egress-proxy tests, and zenova doctor --target use the same seven-layer attribution for upstream connect failures (one-to-one with the ConnectivityFailureKind enum):

Request identifier

When investigating, take the request identifier first: response header x-request-id is the logical request id on the gateway. The request_id field in OpenAI / Anthropic error bodies is the same value. Attach that value when you report to an administrator so the full call record can be found.

Streaming errors

When a streaming request fails after output has started, the gateway sends one in-stream error frame (same shape as the chosen protocol's error body) and then ends the stream normally. Content and usage already emitted are billed and shown as usual. reason is still read from the table below.

Full reason table (318 items)

The table lists every reason the data plane may emit, in kernel export order. Rendered fields are the OpenAI-protocol rendering. Anthropic / Gemini type / status are projected from the same reason.