Docs · API

Errors

HTTP status codes and error codes returned by the gateway and worker routes.

On this page

HTTP errors return a single error object:

{ "error": { "code": "VALIDATION_FAILED" } }

The public API does not include a human-readable message in HTTP error bodies. Fatal errors after an SSE stream has started include both code and message in the event payload.

User API and gateway

Status	Code	When it is returned
400	`VALIDATION_FAILED`	The JSON body or a field does not match the request schema, or the model key is unknown or inactive.
401	`UNAUTHORIZED`	The API key is missing, invalid, revoked, expired, or belongs to an inactive user.
402	`INSUFFICIENT_CREDITS`	The request cannot reserve its credit hold.
404	`JOB_NOT_FOUND`	A job ID is not a valid UUID or the job does not belong to the caller.
409	`CANCELLED`	The job was cancelled before it completed.
409	`INVALID_TRANSITION`	The job is already in a terminal state and cannot change.
413	`CONTEXT_LIMIT`	The estimated input is above 2,048 tokens.
429	`RATE_LIMITED`	The per-key 60-requests-per-minute window is exhausted.
500	`INTERNAL`	An unexpected gateway or execution failure occurred.
503	`NO_CAPACITY`	The scheduler could not reserve an eligible worker, including after a bounded replan.
503	`PROMPT_HOLD_UNAVAILABLE`	Worker-executed mode could not write the prompt hold, so no worker could accept the job.
504	`DEADLINE_EXCEEDED`	The overall job deadline passed.
504	`STAGE_TIMEOUT`	A pipeline stage exceeded its stage deadline.

409 CANCELLED and 409 INVALID_TRANSITION are normally internal lifecycle outcomes; a client that disconnects during a stream may not receive them.

Streaming errors

Before the first SSE byte, failures use the HTTP status and body above. After the stream starts, the gateway writes one error event and closes the connection:

data: {"error":{"code":"DEADLINE_EXCEEDED","message":"job deadline exceeded"}}

There is no trailing data: [DONE] on a failed stream. A stream without the sentinel is incomplete.

Worker control and execution

Worker routes use the same { "error": { "code": "..." } } shape. These codes are normally handled by the worker, not by an API client:

Status	Code	Meaning
400	`VALIDATION_FAILED`	A worker request body or path parameter failed validation.
401	`UNAUTHORIZED`	The worker session token is missing, invalid, or revoked.
404	`ASSIGNMENT_NOT_FOUND`	The assignment does not exist for this worker.
409	`ASSIGNMENT_NOT_READY`	The prompt hold is absent or the assignment is not in an acceptable state.
409	`BUILD_SKEW`	The front and RPC workers advertise different llama.cpp builds.
409	`INVALID_CHUNKS`	A token submission is malformed or out of order.
410	`PROTOCOL_INCOMPATIBLE`	The worker protocol version is not accepted.
413	`PAYLOAD_TOO_LARGE`	A token payload exceeds the accepted size.
500	`INTERNAL`	Unexpected control-plane or execution failure.

Scheduler reservation failures can also surface as 409 NO_CAPACITY during a replan. See Worker troubleshooting for the worker-side checks.