The KubeMQ Kafka connector answers every failure with a standard Kafka protocol error code — the same numeric ErrorCode field (top-level, per-partition, or per-resource, depending on the API) a stock Kafka client already knows how to interpret. There is no custom error vocabulary: branch your client's retry/reconfigure logic on the numeric code exactly as you would against real Kafka.

Retriable vs. non-retriable. Codes marked retriable reflect a transient condition — the broker isn't ready, a race was lost, a coordinator pointer is stale — that a client's normal backoff-and-retry resolves. Non-retriable means resending the identical request will never succeed; something has to change first.

Version negotiation

Code	Error	What triggers it
35	`UNSUPPORTED_VERSION`	The request's version falls outside that key's advertised `[min, max]` window (see Capabilities). Encoded at the key's max version so the client can parse it and renegotiate via `ApiVersions`.

Produce and fetch (data plane)

Code	Error	What triggers it
1	`OFFSET_OUT_OF_RANGE`	`Fetch`/`ListOffsets` requested an offset below the log start or above the high watermark — never used for a valid empty fetch at offset 0. Non-retriable at that offset.
2	`CORRUPT_MESSAGE`	A `Produce` batch failed decode — CRC mismatch, an incomplete/oversized batch, a bad `Magic` byte, or a negative `FirstSequence` from an idempotent producer. Non-retriable.
3	`UNKNOWN_TOPIC_OR_PARTITION`	The topic or partition doesn't exist and auto-create didn't apply.
5	`LEADER_NOT_AVAILABLE`	The broker isn't accepting traffic yet — still starting, or a just-promoted leader catching up on Raft. Retriable.
6	`NOT_LEADER_OR_FOLLOWER`	A clustered follower answers this on `Fetch` so the client's metadata refresh re-routes it to the leader. Retriable.
10	`MESSAGE_TOO_LARGE`	A `Produce` partition's `Records` exceed `MaxMessageBytes` (default 1 MiB). Non-retriable — the producer must reconfigure.
17	`INVALID_TOPIC_EXCEPTION`	The topic name fails KubeMQ's channel-name validation — kept distinct from an authorization deny so it never leaks "denied" to an unauthorized caller.
21	`INVALID_REQUIRED_ACKS`	`Produce`'s `Acks` is set to something other than `0`, `1`, or `-1`. Unreachable by a conformant client. Non-retriable.
45	`OUT_OF_ORDER_SEQUENCE_NUMBER`	An idempotent producer's per-`(PID, partition)` sequence check found a gap.
46	`DUPLICATE_SEQUENCE_NUMBER`	The same `(PID, partition)` sequence was already accepted — the connector dedups the retry.
59	`UNKNOWN_PRODUCER_ID`	The batch's producer ID has no live sequence-tracking record — expired, or never seen.
74	`FENCED_LEADER_EPOCH`	The client's `CurrentLeaderEpoch` is older than the partition's live epoch. Retriable.
75	`UNKNOWN_LEADER_EPOCH`	The client's `CurrentLeaderEpoch` is newer than what this node knows. Retriable.
100	`UNKNOWN_TOPIC_ID`	A `Metadata` v10+ request named a `TopicID` (KIP-516) that doesn't resolve to any discoverable topic.

Consumer-group coordinator

Code	Error	What triggers it
14	`COORDINATOR_LOAD_IN_PROGRESS`	The durable offset store hasn't finished replaying at boot. Retriable — a background sweep retries until it succeeds.
15	`COORDINATOR_NOT_AVAILABLE`	The broker isn't accepting group-coordinator traffic yet. Retriable.
16	`NOT_COORDINATOR`	This node isn't the caught-up Raft leader for the group; surfaces only when the leader-proxy hop fails. Retriable.
22	`ILLEGAL_GENERATION`	A Join/Sync/Heartbeat names a generation the coordinator has already moved past.
23	`INCONSISTENT_GROUP_PROTOCOL`	The group's members can't agree on a common protocol/assignor during a rebalance.
24	`INVALID_GROUP_ID`	An empty `group.id`.
25	`UNKNOWN_MEMBER_ID`	The presented `member.id` is unknown — never joined, already reaped, or an unrecognized static-instance mapping.
26	`INVALID_SESSION_TIMEOUT`	`JoinGroupRequest.SessionTimeoutMillis` falls outside the coordinator's accepted bounds.
27	`REBALANCE_IN_PROGRESS`	The group is (now) rebalancing — the member must rejoin.
68	`NON_EMPTY_GROUP`	`DeleteGroups` targeted a non-Empty group, or `OffsetDelete` targeted an active non-consumer-protocol group.
69	`GROUP_ID_NOT_FOUND`	The named group is unknown to the registry and the durable offset store, or its state is Dead.
79	`MEMBER_ID_REQUIRED`	KIP-394's two-round `JoinGroup` handshake: an empty-`MemberID` round-1 request (v4+) gets a freshly minted ID and this code; the client resends with it.
81	`GROUP_MAX_SIZE_REACHED`	The group, or the coordinator-wide group cap, is already at its configured ceiling.
82	`FENCED_INSTANCE_ID`	KIP-345 static membership: `group.instance.id` maps to a different `member.id` than the requester — a displaced or duplicate static instance.
86	`GROUP_SUBSCRIBED_TO_TOPIC`	`OffsetDelete` targeted a `(topic, partition)` a live member still subscribes to — deleting it would rewind that consumer.
88	`UNSTABLE_OFFSET_COMMIT`	`OffsetFetch` set `RequireStable` (v7+) while the group holds a staged, uncommitted transactional offset. Retriable.

Topic and partition admin

Code	Error	What triggers it
36	`TOPIC_ALREADY_EXISTS`	`CreateTopics` named a topic that already exists.
37	`INVALID_PARTITIONS`	`CreatePartitions` requested a same-or-lower count, or one above the 256-partition cap; also `CreateTopics`'s `NumPartitions` over that cap.
38	`INVALID_REPLICATION_FACTOR`	A request asked for `ReplicationFactor > 1` — replication is internal to Raft, never exposed as separate Kafka replicas.
40	`INVALID_CONFIG`	An unsupported config value — an invalid `cleanup.policy`, `message.timestamp.type=LogAppendTime`, or an `APPEND`/`SUBTRACT` op on a scalar config.
41	`NOT_CONTROLLER`	An admin write landed on a node that isn't the caught-up leader. Retriable — the client retries against the controller.
42	`INVALID_REQUEST`	A malformed field — most commonly a present-but-empty `transactional.id`, or one failing channel-name validation.

Transactions

Code	Error	What triggers it
47	`INVALID_PRODUCER_EPOCH`	A `Produce` arrived with an epoch below the live epoch on record — a zombie holding a stale epoch. Non-retriable; the producer must re-run `InitProducerId`.
48	`INVALID_TXN_STATE`	A transactional batch arrived in the wrong coordinator state; also reused by `AddPartitionsToTxn`/`AddOffsetsToTxn`/`EndTxn`/`TxnOffsetCommit` for their own state violations.
49	`INVALID_PRODUCER_ID_MAPPING`	A KIP-360 request named a `(transactional.id, PID)` pair with no durable record — the ID is new, or was tombstoned since the client last saw it.
50	`INVALID_TRANSACTION_TIMEOUT`	`TransactionTimeoutMillis` is `<= 0` or exceeds the coordinator-wide ceiling.
51	`CONCURRENT_TRANSACTIONS`	Two state/epoch-transition attempts raced for the same `transactional.id`. Retriable.
53	`TRANSACTIONAL_ID_AUTHORIZATION_FAILED`	The principal lacks Write on the `transactional.id` resource.
55	`OPERATION_NOT_ATTEMPTED`	`AddPartitionsToTxn` named a partition that doesn't exist alongside ones that do — the existing ones answer this instead of a false success.
87	`INVALID_RECORD`	A client submitted a control batch — those are broker-internal; the only real producer is the coordinator's own commit/abort marker.
90	`PRODUCER_FENCED`	A KIP-360 `InitProducerId` epoch is strictly above the live durable epoch — the only branch that answers 90.

KIP-890 transaction protocol V2 is not shipped — no per-EndTxn epoch bump. EndTxn writes a real in-log COMMIT/ABORT marker, but soundness stays bounded to the V1 wire scope in Capabilities.

Authorization

Code	Error	What triggers it
29	`TOPIC_AUTHORIZATION_FAILED`	The principal lacks the required topic ACL — Produce needs Write; Fetch/ListOffsets/OffsetFetch need Read.
30	`GROUP_AUTHORIZATION_FAILED`	The principal lacks the required group ACL — OffsetCommit/OffsetDelete/DeleteGroups need Write; Join/Sync/Heartbeat/Leave/DescribeGroups need Read.
31	`CLUSTER_AUTHORIZATION_FAILED`	The principal lacks Describe on the cluster resource — e.g. `DescribeCluster`(60).

Every authorization deny above is non-retriable — re-authenticate or request a policy grant rather than retry unchanged.

SASL

Code	Error	What triggers it
33	`UNSUPPORTED_SASL_MECHANISM`	The client's `SASLHandshake` names a mechanism this listener doesn't offer — for example, `OAUTHBEARER` on the plaintext listener (TLS-only). The response still lists supported mechanisms; the connection stays open.
34	`ILLEGAL_SASL_STATE`	`SASLAuthenticate` arrived before a successful `SASLHandshake` selected a mechanism.
58	`SASL_AUTHENTICATION_FAILED`	Credentials didn't validate — unknown user or wrong password/token, deliberately indistinguishable to the client. The connection is closed.

Security and resource admin

Code	Error	What triggers it
54	`SECURITY_DISABLED`	A SCRAM-credential or ACL mutation was refused — both are config-managed (`Connectors.Kafka.Credentials`), not runtime-mutable. Also answered when authorization is off entirely.
61	`DELEGATION_TOKEN_AUTH_DISABLED`	Any delegation-token request — KubeMQ does not implement delegation tokens; switch those principals to SASL/SCRAM or mTLS.
91	`RESOURCE_NOT_FOUND`	`DescribeUserScramCredentials` named a user with no SCRAM credentials configured. Non-retriable.

Code	Error	What triggers it
123	`INVALID_SHARE_SESSION_EPOCH`	An incremental `ShareFetch` arrived for a share session the broker no longer holds — a failover, or the session was reaped. The client resets and reopens at epoch 0.

Error Codes

Version negotiation

Produce and fetch (data plane)

Consumer-group coordinator

Topic and partition admin

Transactions

Authorization

SASL

Security and resource admin

Capabilities

Limits & Rules

Transactions & EOS

Authentication

On this page