Errors & rejections

The error envelope

Every non-2xx response has one shape:

{"error": {"code": "model_waking", "message": "…", "details": {"eta_s": 20}}}

code is stable and machine-matchable; message is human-readable; details is optional structured context.

Codes you handle in normal operation

status	code	what to do
202	model_waking	Nothing charged, nothing queued. Retry after Retry-After / details.eta_s.
202	queue_backlog	Same contract as model_waking.
202	still_processing	The render IS running. Poll GET /v1/requests/{details.request_id}?wait=30. Billed once, at completion.
401	missing_api_key / invalid_api_key	Send Authorization: Bearer epm_live_….
402	insufficient_credit	Top up; the pre-flight check quotes the exact price.
403	adhoc_loras_locked	The endpoint serves its stored recipe only; create one with allow_adhoc_loras: true.
404	model_not_found / endpoint_not_found	Also returned for assets you can't access or components withdrawn from composition — absence and denial are indistinguishable by design.
409	model_not_ready	Onboarding hasn't parked yet; check the onboarding request.
409	lora_not_servable	LoRAs don't serve alone — put it in a composition.
422	validation codes	The message names the field and constraint.

Onboarding rejection codes

When onboarding rejects a model, the state is rejected and rejection_reason starts with one of these classes:

code	meaning
not_safetensors	Not a readable safetensors file (pickle checkpoints are never accepted).
truncated	File shorter than its header claims — usually a broken download or early-access stub.
too_small	Below the family's minimum plausible size.
quantized	FP8/INT quantized checkpoint — dequantization isn't supported.
v_prediction	v-prediction checkpoint — the current sampler assumes epsilon prediction and would render it incorrectly. Support planned.
unknown_family	Key schema matches no enabled family.
missing_slots / shape_mismatch	The checkpoint doesn't cover the family's required tensors exactly.
lora_format	LoRA isn't plain kohya pairs (LyCORIS/DoRA not yet supported).
lora_unmapped	A LoRA module doesn't map onto the base family — usually a family mismatch.
lora_rank	Rank above the supported maximum (256).
unsupported_source	The Civitai listing isn't a Checkpoint or LORA, or its license isn't permissive (Rent/Sell).
compiler_crash / compiler_timeout	The compile worker died or exceeded its budget — resubmit; if it persists, the file is doing something pathological.

Rejections are informational, not punitive: fix the cause and resubmit.