Skip to content

Error codes ​

Every error is an HTTP status plus a JSON envelope:

json
{"error": {"code": "not_homed", "message": "axis j1 must be homed before absolute moves"}}

Clients should branch on code, not on message.

CodeHTTPMeaning
bad_request400Malformed request; e.g. flash without "confirm": true, build for a virtual board, home on an axis without homing config, a job that is not a succeeded build
validation_failed400Motion rejected by the engine's planner: outside soft limits, velocity too high, non-finite value
not_homed400Absolute move on an unhomed axis
unauthorized401Missing or wrong token. Carries WWW-Authenticate: Bearer
forbidden403Role too low; or a cross-origin request, or a disallowed Host while auth is off
not_found404Unknown resource, e.g. firmware job
unknown_axis404Axis id not in the robot configuration
unknown_command404No such command name
method_not_allowed405With an Allow header
invalid_state409Not allowed in the current robot state (moving while not ready; flashing while drives are on or another job runs)
unsupported_media_type415POST with text/plain, a form, or multipart content type
rate_limited429Too many POSTs, or too many failed logins. Carries Retry-After
mcu_error502The MCU rejected the request or the link failed
engine_unavailable503ratavyr is not connected to the engine. /api/info → engine_error says why
engine_timeout504The engine did not answer within 5 s
internal500Anything else

Mapping from the engine ​

The engine reports gRPC status codes with the precise code in the motioncore-error-code trailer. ratavyr passes that code through and picks the HTTP status from it. See engine gRPC errors.

Robot faults are not errors ​

A fault — communication_lost, limit_hit, emergency_stop and so on — is robot state, reported in telemetry's fault field, not as an HTTP error. See MotionCore: faults.

Part of MotionCore. A software stop never replaces a hardware E-stop circuit.