Docs / Troubleshooting

Errors and retries

LaneZero maps provider failures into stable error types. Use the HTTP status, machine-readable code, and request phase to decide what to do next.

Error envelope

Gateway-generated errors use an OpenAI-style JSON object with exactly three fields inside error.

{
  "error": {
    "message": "missing or invalid gateway API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

message

A safe human-readable explanation. Provider key material is never included.

type

The broad provider-independent category. Use this for general handling.

code

The specific gateway condition. Use this when recovery differs within a type.

Malformed management JSON, query strings, or path values can be rejected by the web framework before LaneZero creates this envelope. Those extractor responses can use a different status and plain-text body. Chat request JSON is explicitly normalized into this envelope.

Unified error taxonomy

Type	Status	What triggers it	Caller retry
`authentication_error`	401	Missing, malformed, invalid, or revoked gateway key. Missing provider credentials. Provider credentials rejected with 401 or 403. Google can also map an authentication-marked 400 here.	No. Fix or replace credentials first.
`rate_limit_error`	429	The per-gateway-key limit is exhausted, or every usable fallback ends in a provider rate limit.	Yes. Back off with jitter.
`invalid_request_error`	400	Malformed chat JSON, invalid model syntax, unknown catalog model, invalid tool-call data, or a provider non-429 4xx response.	No. Change the request.
`upstream_error`	502	Provider 5xx, transport failure, malformed provider JSON or SSE, early stream termination, or another provider-protocol failure.	Usually. Consider whether partial output was received.
`timeout_error`	504	An explicit provider request deadline or streaming first-byte deadline expires.	Usually. Use backoff and a bounded attempt count.

The adapter-level taxonomy above is shared by all 12 providers. LaneZero also returns these gateway and management types:

Type	Status	What triggers it	Caller retry
`invalid_request_error`	404	A requested gateway key or provider key does not exist for the signed-in user.	No. Refresh local state.
`service_unavailable_error`	503	Authentication database unavailable with no usable cache, account database failure, vault failure, or management routes used without a database.	Yes for temporary backends. No for `database_disabled` until configuration changes.
`not_implemented_error`	501	A recognized provider has no adapter in the running build.	No. Select an implemented provider.
`server_error`	500	The GitHub OAuth response configuration cannot be represented safely.	No immediate retry. Report server configuration.

Common error codes

Code	Status	Meaning
`invalid_json`	400	The chat body did not deserialize as a supported request.
`model_not_found`	400	At least one requested model is absent from the embedded catalog.
`invalid_request`	400	The adapter rejected local translation or the provider returned a non-429 4xx.
`invalid_api_key`	401	A gateway key is invalid, or an upstream provider rejected its credentials.
`missing_provider_key`	401	No passthrough or vaulted credential was found for any usable chain entry.
`invalid_session`	401	The management session cookie is missing, invalid, or expired.
`rate_limit_exceeded`	429	A gateway-key or provider rate limit prevented completion.
`upstream_error`	502	The selected provider failed after LaneZero exhausted available fallback.
`timeout`	504	The selected provider exceeded an explicit deadline after fallback was exhausted.
`auth_backend_unavailable`	503	The gateway-key lookup failed and no cached record could authorize the request.
`account_backend_unavailable`	503	A management database operation failed.
`vault_unavailable`	503	Provider credential encryption or decryption failed.
`database_disabled`	503	A management or OAuth route was called in passthrough-only mode.

Retry guidance

Inspect error.type and error.code. Do not retry authentication or invalid-request failures unchanged.
For 429, 502, 503, or 504, use exponential backoff with jitter and a bounded caller-side attempt count.
Check x-lz-attempts before adding more attempts. LaneZero may already have called as many as three providers for one request.
Check x-lz-provider and x-lz-fallback when diagnosing provider-specific behavior.
For a stream that produced content or tool calls, treat a retry as a new generation. Do not blindly repeat side effects caused by a partial tool-call sequence.

LaneZero fallback

Within one request, LaneZero advances on provider 429, 5xx, timeout, transport, and protocol failures. It does not advance on 400, 401, 403, or other non-429 4xx responses.

Retry-After

LaneZero uses an upstream Retry-After internally only when the delay is valid and no more than two seconds. The current error response does not forward that header to the caller.

Streaming errors

Before the first normalized output chunk, a retryable failure can advance the fallback chain. After the first chunk, the response is committed and no provider switch occurs. A mid-stream failure keeps HTTP status 200 and writes:

event: error
data: {"error":{"message":"Anthropic reported a streaming error","type":"upstream_error","code":"upstream_error"}}

data: [DONE]

SSE clients must listen for named error events. Checking only the initial HTTP status or ordinary data: chunks will miss a mid-stream failure.