Skip to content
Docs

API Errors

Read X-Lifeboat-Reject-Reason first when present; it names the cause.

By status

Section titled “By status”
Status Body Cause Fix
401 — Missing or wrong bearer token Check the header and the key
402 license_required Grace elapsed, no licence Activate — the console still works
404 — On chat/completions, a genuine error. On rerank, score or audio, that engine does not implement it Nothing — already retried elsewhere
413 request_too_large No backend’s input cap covers it Raise the cap, or shorten the prompt
501 no_embedding_backend /v1/embeddings, no embedding server Start one
501 no_diffusion_backend Image or video endpoint, no diffusion server Start one
501 tts_engine_unavailable This image has no text-to-speech engine Use an image that does
503 no_backends Nothing running for that model Usually a name matching nothing — check GET /v1/models
503 embedding_only_pool Generation request aimed at an embedding model Send the right model name
503 (none) Every backend at capacity, queue off Raise concurrency, add a replica, or use queue-all
503 queue_full Queue at its depth ceiling Capacity, not tuning
504 queue_timeout Waited longer than allowed Add capacity

Capacity or configuration?

Section titled “Capacity or configuration?”

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

  • Effective 4 while configured is 32 ⇒ superfast is capping you deliberately. That is a mode decision, not a shortage.
  • Effective equals configured and you are still rejecting ⇒ a genuine capacity problem.

That distinction saves the most time, so it is in the body rather than only in /api/lb/state.

Capability misses are not health signals

Section titled “Capability misses are not health signals”

A 404 or 501 on rerank, score, embeddings or audio means that engine does not implement that endpoint — engines differ. Lifeboat fails the request over to the next candidate and deliberately does not penalise the backend, because one rerank probe should not take a healthy chat backend out of rotation.

It is scoped: chat and completions are implemented everywhere, so a 404 there is a real error and surfaces immediately.

Errors carried inside a 200

Section titled “Errors carried inside a 200”

The one to watch for. An engine can return an error message with a 200 status — most commonly an embedding model asked to generate. Lifeboat’s direction filter prevents the common case, but a client talking to a backend port directly bypasses it. Route through the control plane.

Sources and references

Section titled “Sources and references”