Errors

Every failed request returns a structured JSON body with the same shape, and the HTTP status equals the body's status_code. Agents branch on the stable, machine-readable code (a dotted <domain>.<reason> string) rather than parsing prose.

{
  "detail": "A human-readable message.",
  "errors": [],
  "status_code": 400,
  "code": "user.validation"
}

Typed errors

These are the codes a caller can rely on. User-branch errors carry the message verbatim (a caller mistake); system-branch errors are sanitized before they reach you.

Error	code	HTTP	Meaning
UserError	user.error	400	A custom exception for user-facing errors in model-related workflows.
ValidationError400	user.validation	400	Invalid payload values that pass type checks but fail business rules.
UnsupportedOptionError	user.unsupported_option	400	The caller requested an option/variant/parameter the model doesn't support.
ResourceNotFoundError	user.resource_not_found	404	A user-referenced resource (e.g. a named input/asset) does not exist.
ServerError	system.error	500	Base class for internal failures (not the caller's fault).
ModelExecutionError	system.model_execution	500	The underlying model/inference call failed during execution.

Other responses

• 422 — schema validation. A malformed body (missing/extra field, wrong type) is rejected before the model runs. code is null; per-field details are listed under errors.
• 5xx — unexpected failure. Any error not mapped above returns a sanitized 500 with code null (or the raised code when available); filesystem paths and tokens are stripped from the message.
• Gateway transport. The gateway itself returns 404 when the target model is not deployed, 503 when the model backend is unreachable, and 504 when model execution times out.