Errors

FlowLayer V1 exposes a fixed protocol error-code set.

Error shapes in protocol flow

Errors can appear in three places:

1. Protocol-level error message:

{
  "type": "error",
  "id": "cmd-42",
  "payload": {
    "code": "missing_name",
    "message": "command.name is required"
  }
}

2. Rejected command ack (accepted: false):

{
  "type": "ack",
  "id": "cmd-42",
  "payload": {
    "accepted": false,
    "error": {
      "code": "unknown_service",
      "message": "service \"billing\" is not defined"
    }
  }
}

3. Failed result for an accepted command (ok: false):

{
  "type": "result",
  "id": "cmd-42",
  "payload": {
    "ok": false,
    "error": {
      "code": "internal_error",
      "message": "..."
    }
  }
}

Error code catalog

Code	Category	Meaning
invalid_json	Validation	Incoming frame is not valid JSON
missing_type	Validation	type is missing or empty
unknown_type	Validation	type is not recognized
missing_id	Validation	Required id is missing
missing_name	Validation	Required name is missing
invalid_payload	Validation/command input	Payload shape or field values are invalid
unsupported_message_type	Routing	Client sent a message type that is not accepted as client input
unknown_command	Runtime command routing	Command name is not supported
unknown_service	Runtime command validation	Referenced service is not defined
service_busy	Runtime state	Service is currently transitioning (starting/stopping)
internal_error	Runtime execution	Server failed while handling an accepted operation

Validation vs runtime behavior

Validation-layer failures (for example malformed envelope fields) are protocol errors.

Runtime command handling errors split in two patterns:

• Immediate rejection via ack.accepted = false:
  • unknown_command
  • unknown_service
  • service_busy
  • command payload problems such as invalid payload.service or invalid get_logs parameters (invalid_payload)
• Later failure via result.ok = false:
  • internal_error

Client reaction guidance

Code family	Client action
invalid_json, missing_*, unknown_type, invalid_payload	Treat as client-side request bug; fix request construction before retry
unsupported_message_type	Ensure client sends only command messages upstream
unknown_command	Check hello.payload.capabilities; downgrade or guard unsupported actions
unknown_service	Refresh service list from snapshot or get_snapshot, then retry with valid name
service_busy	Retry later with backoff
internal_error	Surface error and allow retry; do not assume operation succeeded

Always correlate command outcomes by id when it is present.

See Message Envelopes for correlation details and WebSocket Lifecycle for session sequencing.