Troubleshooting — Failing Requests

Read X-Lifeboat-Reject-Reason first. It names the cause; everything below is what to do about each one.

Quick map

Symptom	Cause	Fix
503, no reason	Capacity, queue off	Raise concurrency, add a replica, or queue-all
503 `queue_full`	Queue at its ceiling	Capacity, not tuning
504 `queue_timeout`	Sustained overload	Add capacity
413 `request_too_large`	Input cap too low	Raise it, or shorten the prompt
503 `no_backends`	Nothing running for that model	Check the name against `GET /v1/models`
503 `embedding_only_pool`	Chat request aimed at an embedding model	Send the right model
501 `no_embedding_backend`	No embedding server running	Start one
501 `no_diffusion_backend`	No diffusion server running	Start one
401	Bad or missing token	Check the header
402 `license_required`	Grace elapsed	Activate — console still works

Capacity or configuration?

503 and 504 bodies report the routing mode and the effective per-backend limit.

Effective 4, configured 32 ⇒ superfast is capping you deliberately. Not a shortage.
Effective equals configured and still rejecting ⇒ genuine capacity.

An embeddings request gets a chat-model error

The model name did not match a running server. Send a name from GET /v1/models.

Lifeboat refuses by direction rather than guessing, so /v1/embeddings cannot be answered by a chat model and vice versa. Without that, an unresolvable name meant the request was routed by position and answered wrongly about half the time — an error carried inside an HTTP 200, which reads as a flaky backend.

An error inside a 200

The case to watch for. An engine can return an error message with a 200 status — most often an embedding model asked to generate.

Lifeboat’s direction filter prevents this through the control plane. A client talking to a backend port directly bypasses it. Route through the control plane; do not expose model server ports.

A prompt is rejected for exceeding context

exceeds the model’s maximum context length

Your client believes the window is larger than it is. Two usual causes:

The client budgets against the cache size rather than the per-request limit. The cache is shared across concurrent requests and is often far larger; Lifeboat advertises the per-request limit for exactly this reason.
The client adds a reserved completion on top of a prompt that already fills the window. The input alone fits; input plus reservation does not.

Read what GET /v1/models reports and budget against that. See Context length.

404 on rerank, score or audio

Not an error to chase: that engine does not implement that endpoint, and Lifeboat has already failed the request over to another candidate. The backend is deliberately not penalised — one rerank probe should not remove a healthy chat backend from rotation.

A 404 on chat or completions is a real error, because those are implemented everywhere.