Error codes and fault states

When rt-control refuses a request it returns HTTP 409 (413 for an oversized body, 404 for an unknown resource) with a reason code in error. This page lists every reason in the contract, grouped by area, with the operations that can return it. It also covers the numeric reasons inside native receipts, the execution fault bits and the per-axis readiness states in Status.

The reason list is generated from reasons in rt-core/protocol/application-v1.schema.json, which the contract calls the closed catalogue of adapter-owned labels. The same names are exported as constants by all three clients: control.Reason… in Go, rosie::rt_control::Reason… in C++ and Reason… in TypeScript.

Reading an error#

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "start_trajectory",
  "error": "not_ready",
  "native_result": {
    "Sequence": 31,
    "Handle": 7,
    "Generation": 3,
    "Operation": 292,
    "Result": 1,
    "Reason": 2,
    "AxisMask": 511
  }
}

• error is a catalogue label, or a diagnostic that starts with one (native_limit_exceeded: segment=2 sample=118 axis=J3). Some errors are open diagnostics with no label: JSON decoding, I/O, context and native text such as RTCore rejected operation 0x124: reason 2. Match on the leading label.
• native_result is present when the core refused a command. Read its numeric Reason in native command reasons.
• native_jog_result is present when the jog lane refused. Read StateReason, ControlReason or UpdateReason in native jog reasons.
• data.limit_violation accompanies native_limit_exceeded and native_segment_rate_exceeded from a program upload. It gives kind (position or velocity), segment, sample, axis, value, limit and unit (rad or rad/s).

Treat an unknown label, a malformed reply or a transport failure as an unknown outcome. Stop producing motion, send an authenticated stop if you can, and reconcile Status before acquiring again.

rt-control reason codes#

All 153 reasons, in 13 groups. Returned by links to the operation on the rt-control HTTP API page. The meaning is the contract's own text where it gives one, and otherwise a description of the code that raises the reason.

Request envelope and transport#

Authority and session#

Handles#

Native admission#

Program admission and execution#

Dense program format (.rdt)#

Recovery and anchors#

Cell I/O#

Jog lane and jog clock#

Events, telemetry and resources#

WebSocket transport (remote jog)#

Remote TLS (startup and handshake)#

Startup and socket ownership#

Four error texts carry detail after a fixed prefix: unmapped_dense_axis: <axis>, native_limit_exceeded: segment=<index> sample=<index> axis=<id>, discard preparation <handle>: <cause> and jog_native_rejected_<number> (a WebSocket jog refusal carrying a native jog reason). At startup, remote CRL signature: <cause> reports a CRL that the CA did not sign.

Native command reasons#

The numeric native_result.Reason in a refused command, from reasons in rt-core/protocol/control.json. native_result.Result is 0 accepted, 1 rejected or 2 prepared.

rt-control translates some of these into labels: 8 becomes outside_limits_outward, the cell I/O reasons 9..18 become their labels for I/O-carrying calls, and 2 or 3 during a Start become not_ready or mode_conflict. Anything else arrives as native_rejected. Reason 5 (capacity) during a program upload arrives as busy, and reason 6 (invalid trajectory) retires every prepared handle.

Native jog reasons#

The numeric reasons of the jog lane, from jog_reasons in control.json. They appear in JogObservation (StateReason, ControlReason, UpdateReason), in /v1/jog/ingress counters and in WebSocket jog_native_rejected_<n> refusals. Reason 14 (limited) is an accepted, governed state, not a failure.

Native grant reasons#

The numeric GrantReason in GrantObservation, from grant_reasons in control.json.

Execution fault bits#

core.execution_fault_reasons in Status is a bit mask of latched execution faults. RecoveryStatus.faults[] names each latched bit with its affected axes and recovery class. This table is generated from rt-core/include/fault_recovery.hpp, whose own comments call the policy unverified.

Loss of trusted feedback can also require Home even when the table says No. Unknown bits persist.

reset_fault outcomes per bit are cleared, persists or rehome_required. Any persistent selected condition refuses the whole reset with fault_persists.

Axis readiness#

Each entry of axes[] in Status has a readiness string: the first failing gate for that axis, in this order. It is an observation, not authority: the group gates (lease, Arm, bus, faults, configuration) still apply at every Start.

The code also defines warning_tolerated: one tolerated drive warning on an axis without an encoder battery. It grants nothing, and Home and Enable keep their normal gates.

Handle states#

HandleRecord.state, from handle_states in the schema. Only prepared can start, and terminal states never regain permission.

Other components#

Components that call rt-control add their own refusal codes. They are documented with each component: