Errors

Error responses use a uniform shape:

{
  "error": {
    "code": "unknown_model",
    "message": "Model 'foo' is not in /capabilities.models",
    "details": { "available_models": ["kimodo-soma-rp"] }
  }
}

Field	Type	Notes
error.code	string	Machine-readable code from the table below
error.message	string	Human-readable message; safe to surface to end users
error.details	object | null	Optional code-specific extra context

Error codes

Code	HTTP	Meaning
schema_validation	422	Request fails JSON schema validation (e.g. a video_reference with both or neither of video.url / video.data, a non-https URL, bad base64, or start_s ≥ end_s). details.errors lists each failure (location, type, message; the offending input is not echoed)
unknown_model	400	model is not in /capabilities
retargeting_unsupported	400	Custom skeleton sent to a backbone with supports_retargeting=false
unsupported_constraint	400	A constraint type is not in model.supported_constraints
unsupported_segment	400	A segment type (e.g. "pose") is not in model.supported_segments. Checked before the segment's payload is read. A type the server doesn't know at all is 422 schema_validation
unknown_joint	400	A constraint references a joint name not in skeleton.joints (for a motion_reference: not in its own skeleton when it carries one)
invalid_skeleton	400	Skeleton (the request's, or a motion_reference's own) has no root, multiple roots, cycles, or out-of-order joints; or (1.2) has a non-identity rest_rotation the server can't honour
frame_out_of_range	400	A constraint references a frame index outside the request timeline
invalid_request	400	1.2. Parts of the request that are valid alone but can't go together (e.g. a motion_reference clip that lacks its skeleton's root joint; a video_reference whose video can't be fetched or decoded, or has no person in it)
invalid_options	400	An option value is out of range (e.g. diffusion_steps: 9999) or inconsistent (e.g. guidance.weight length mismatch), or a reference is over its limit: a motion_reference clip over max_reference_frames, a video_reference reading more than max_video_seconds (details.segment names it)
version_unsupported	400	Server does not implement the requested protocol_version
unauthorized	401	Missing or invalid credentials
forbidden	403	Authenticated but not permitted to call this model
payload_too_large	413	Request body exceeds model.limits.max_request_bytes (the SDK server checks it before parsing), or (1.2) a video_reference's video exceeds max_video_bytes (details: max_video_bytes, video_bytes, segment)
rate_limited	429	Caller is rate-limited; check Retry-After
internal_error	500	Backbone failure (non-retryable; clients SHOULD NOT retry)
resource_exhausted	503	Transient capacity / GPU memory pressure. Retryable with backoff per Retry-After
model_unavailable	503	Model exists but is currently loading or down
timeout	504	Generation exceeded the server-side deadline

Retry semantics

Code	Retry?
schema_validation, unknown_model, retargeting_unsupported, unsupported_constraint, unknown_joint, invalid_skeleton, frame_out_of_range, invalid_request, invalid_options, version_unsupported, unauthorized, forbidden, payload_too_large	No — fix the request
rate_limited, resource_exhausted, model_unavailable, timeout	Yes — honor Retry-After, exponential backoff
internal_error	No — backbone failure, not transient