Skip to content

Errors

The API separates protocol/session failures from command-domain failures.

error_response

Use error_response for protocol, authentication, lifecycle, version, and pre-dispatch message-shape failures. Examples include malformed JSON or envelopes, retired command_id, unsupported external operations, and invalid external operation/field combinations.

error_response does not carry type or protocol_version. Its request_id echoes a valid identifier from the offending request and is omitted when the frame or identifier cannot be correlated.

Error codes:

  • invalid_message
  • unsupported_version
  • unauthorized
  • forbidden
  • response_too_large

response_too_large applies to an external query_state response that would exceed the 1 MiB frame limit. It is always retryable=false, but the processor keeps the connection open and does not advance lifecycle state. Retry with scope="motors" and scope="groups"; do not reconnect merely because this error was returned.

command_response(status="rejected")

Use rejected command responses for command-domain failures and validation performed after a command has been routed to the runtime. In the current 1.0 processor, a missing or unknown target ID, an invalid numeric move target, or an inbound execute_at is rejected with error_code="not_found" and retryable=false. Clients should still validate requests against the public schema and documented field set, and must not send execute_at.

Error codes:

  • not_found
  • conflict
  • rate_limited
  • internal_error

Rejected command responses include retryable.

command_response is a direct response containing type, protocol_version, optional request_id, and status. It does not carry event_type or command_id and must not be processed as a subscribed event.

Retry Guidance

  • Retry rate_limited after backoff.
  • Retry conflict only when retryable=true and after the transient condition clears. This can mean either an exact command retransmission arrived while the original is still in flight, or an active OTA motor job temporarily blocked the target motor or an intersecting group.
  • For an in-flight exact retransmission, wait for the original terminal response. If the connection was lost, retry with the same request_id and payload so a completed response can be replayed without re-execution.
  • For an OTA-gated rejection, wait for the OTA operation to finish and issue the command with a new request_id. The rejected response remains retained under the original retry key for 60 seconds.
  • A changed payload under an existing request_id returns conflict, retryable=false.
  • Do not retry not_found without refreshing state.
  • Reconnect and re-baseline after transport loss or token invalidation. Do not blindly retry an ID-less command after transport loss.