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.