kiit-codes

A Kotlin library for classifying and handling success and failure.

A small, dependency-free status and error taxonomy for application outcomes, with extensible codes, protocol mappings, validation, typed exceptions, and optional Result<T, E> integration.

Overview

Goals

Applications need to communicate a simple idea consistently: what happened? In practice, success and failure get modeled differently across domains, layers, and protocols, which causes recurring problems: no shared taxonomy for classifying outcomes, inconsistent handling across layers, validation/exceptions/statuses/results all using different approaches, similar error types rebuilt project to project, and generic errors that lose domain-specific meaning.

kiit-codes exists to provide a shared, application-level model for these concerns: a fixed taxonomy for consistent classification, extensible codes that preserve domain-specific meaning, and protocol mappings that keep application outcomes independent from how they're transported. The same model is then reused across statuses, validation, exceptions, and result types.

Inspiration

#	Source	What was drawn from it
1	HTTP status codes	Validated against, not derived from — the most common HTTP codes map onto kiit-codes' eight groups without needing a ninth.
2	gRPC status codes	Same validation as HTTP — every gRPC code maps onto the existing eight groups.
3	Scala's Either/Try	Built on Either's two-branch shape, structured around Try's branches, with the Status taxonomy incorporated on top.

Activity

The core classification model has years of internal production use inside the original Kiit framework, powering both mobile and server Kotlin applications, prior to being extracted into this standalone repository. The public package version reflects the standalone repo's youth, not the underlying design's: the classification itself is settled, while newer additions (JS/TS export, iOS/Swift export via SKIE) have less track record and are still being exercised.

Resources

#	Resource	Details
1	Repository	github.com/kiitdev/kiit-codes
2	Maven coordinate	dev.kiit:kiit-codes
3	npm coordinate	@kiit/codes (JS/TS export, not CI-gated yet)
4	Related module	kiit-result builds a Result<T, E> type on top of this same taxonomy (docs page coming next)
5	API reference	Generated from source KDoc, linked here once published

Prefer to see it work first? Jump to the Tutorial. Prefer the reasoning first? Keep reading.

Setup

Install

dependencies {
    implementation("dev.kiit:kiit-codes:1.0.1")
}

Source

#	Item	Link
1	Git Repo	github.com/kiitdev/kiit-codes
2	Root folder of sources in repo	kiit-codes/src/commonMain/kotlin
3	Sample app	samples/sample-kotlin
4	Package Name	kiit.codes
5	Unit Tests	kiit-codes/src/commonTest

Licensed Apache 2.0.

Example

import kiit.codes.*

fun authorize(userId: String, requesterId: String): Status =
    if (userId != requesterId) Restricted.UNAUTHORIZED
    else Succeeded.SUCCESS

when (val status = authorize(userId, requesterId)) {
    is Passed -> log.info("ok: ${status.name}")
    is Failed -> log.warn("failed: ${status.name} — ${status.message}")
}

Concepts

Terms

#	Term	Definition
1	Taxonomy	The overall Status → Group → Code classification system.	More
2	Status	Sealed interface for an operation's outcome: Passed or Failed.	More
3	Group	Second tier: a fixed subtype of Passed/Failed (e.g. Restricted).	More
4	Code	Third tier: an open Status instance within a group (e.g. DENIED).	More
5	Err	Error representation for use with Result/Outcome-style types.	More
6	Checked	Non-monadic validation result reporting every problem, not just the first.	More
7	StatusException	Sealed exception hierarchy carrying a Checked, for exception-only boundaries.	More

Status

Every Status belongs to exactly one Group, and every concrete status value is a Code within that Group. Passed.Succeeded.SUCCESS is the SUCCESS Code inside the Succeeded Group, under the Passed Status. Failed.Restricted.DENIED is the DENIED Code inside the Restricted Group, under the Failed Status.

Succeeded.CREATED is one built-in Code. Its fields, each read on its own line:

val status: Status = Succeeded.CREATED

status.name     // "CREATED"
status.origin   // "kiit"
status.message  // "A new resource was created."
status.success  // true
status.group    // "Succeeded"

Field	Definition
name	Stable SCREAMING_SNAKE_CASE label, e.g. "TOKEN_EXPIRED", for logs.
origin	Where a status came from: "kiit" for built-ins, "custom" by default.
message	Human-readable constant description. Never built from runtime data.
success	true for Passed, false for Failed.
group	The fixed Group this status belongs to, e.g. "Succeeded", "Pending", "Excluded", or "Restricted".

Taxonomy

The full Status → Group → Code taxonomy: every built-in Passed and Failed group, and every built-in code within each.

Tier	Parent	Fixed/Open	Children	Description
1	Status	Fixed	Passed
			Failed
2	Group	Fixed	Succeeded	The operation completed successfully.
			Pending	The operation was accepted but has not yet fully resolved.
			Excluded	The item was intentionally excluded from the operation.
			Information	The response provides information; no operation was performed.
			Restricted	The caller is not allowed.
			Invalid	The request itself is wrong.
			Rejected	The caller was allowed, but the business refuses it.
			Unserved	The system can't serve it right now, though nothing was wrong with the request.
3	Code	Open + Defaults		Ships with common built-in codes (e.g. SUCCESS, DENIED); extensible with custom, domain-specific codes within the same group.

Passed

Passed.success == true.

Group	Code	Description
Succeeded	SUCCESS	The operation completed successfully.
	CREATED	A new resource was created.
	UPDATED	The resource was fully updated.
	PATCHED	The resource was partially updated.
	FETCHED	The resource was retrieved.
	DELETED	The resource was deleted.
	HANDLED	The request was handled; nothing to return.
	REFERRED	The result is at another location.
	EXITED	The application exited cleanly.
Pending	ACCEPTED	The request was accepted.
	QUEUED	The request is waiting to be processed.
	PROCESSING	The request is being processed.
	CONFIRM	The request is awaiting confirmation.
	REDIRECTED	This request is being handled elsewhere.
	SCHEDULED	The operation is scheduled for later.
Excluded	OMITTED	The item was excluded from the result.
	SKIPPED	The item was not processed.
	DISCARDED	The item was processed, then excluded for unrelated reasons.
	CANCELLED	The operation was cancelled by the caller before completion.
	DEDUPLICATED	The duplicate item was not processed.
	DISQUALIFIED	The item was disqualified.
Information	NOTICE	An informational notice.
	ADVISORY	A notice that may need attention.
	METADATA	Information about the application itself was returned.
	HEALTH	The service is healthy and operational.
	DIAGNOSTICS	Diagnostic or operational information was returned.
	MOVED	The resource has permanently moved to a new location.

Failed

Failed.success == false.

Group	Code	Description
Restricted	DENIED	The request was denied.
	UNAUTHENTICATED	Authentication is required.
	UNAUTHORIZED	The caller lacks permission.
	FORBIDDEN	Access to this resource is forbidden.
	LOCKED	Access is locked; resolve the condition to restore access.
	SUSPENDED	Access has been administratively suspended.
Invalid	INVALID_VALUE	The request had an invalid value.
	BAD_REQUEST	The request was malformed.
	NOT_FOUND	The requested route or endpoint does not exist.
	OUT_OF_RANGE	A value was outside the acceptable range.
	PAYLOAD_TOO_LARGE	The payload is too large.
	MISSING_FIELD	A required field was not provided.
Rejected	RULE_VIOLATION	A business rule rejected the request.
	CONFLICT	The request conflicts with the current state.
	NOT_EXISTS	The referenced item does not exist.
	PRECONDITION_FAILED	A required precondition was not met.
	EXPIRED	The item has expired.
	GONE	The resource was removed and is no longer available.
Unserved	UNEXPECTED	An unexpected, unclassified error occurred.
	UNSUPPORTED	This capability is not currently available.
	TIMEOUT	The operation timed out.
	RATE_LIMITED	Too many requests; try again later.
	RESOURCE_LIMITED	A resource limit has been reached.
	UNREACHABLE	A required dependency could not be reached.
	UNDER_MAINTENANCE	The service is temporarily under maintenance.
	INTERNAL	An internal invariant was violated.
	DATA_LOSS	Unrecoverable data loss or corruption occurred.
	DEGRADED	This dependency is degraded; some calls may be refused.
	LEGAL_BLOCK	Access is blocked for legal reasons.
	ABORTED	The operation was aborted; retrying may help.

Err

Error representation for use with Validation, Exceptions, and Result types. This stores instance level error details and the building block for Checked's error list.

sealed class Err {
    abstract val message: String

    data class ErrorInfo(override val message: String, val cause: Throwable? = null) : Err()
    data class ErrorField(val field: String, val value: String, override val message: String) : Err()
    data class ErrorList(val errors: List<Err>, override val message: String) : Err()
}

Variant	Fields	Use
Err.ErrorInfo	message, cause?, ref?	Default implementation: a message with an optional cause.
Err.ErrorField	field, value, message, cause?, ref?	An error on a specific field.
Err.ErrorList	errors, message, cause?, ref?	Wraps a list of other errors.

Builder	Use
Err.of(message)	Plain message, no field or cause.
Err.of(status)	Build directly from a Status.
Err.on(field, value, message)	Error on a specific field, including its value.
Err.on(field, message)	Same, but omits the value — for sensitive fields.
Err.ex(throwable)	Wrap a caught exception or throwable.
Err.obj(any)	Wrap an arbitrary object as the cause.
Err.list(strings, message)	Build an Err.ErrorList from a list of plain strings.
Err.build(any?)	Generic builder that dispatches based on the input's type.

Checked

Non-monadic validation result that reports every problem at once, instead of stopping at the first. Checked(status: Status, errors: List<Err>), reachable only through Checked.success(status) or Checked.failure(status, errors).

class Checked private constructor(
    val status: Status,
    val errors: List<Err>,
) : HasErrors {
    val isValid: Boolean get() = errors.isEmpty()

    companion object {
        fun success(status: Passed = Succeeded.SUCCESS): Checked
        fun failure(status: Failed, errors: List<Err>): Checked
    }
}

#	Trait	Details
1	Invariant	status and errors can never disagree: a passing Checked always has an empty errors list, a failing one always has at least one entry.
2	isValid	Boolean, reflects errors.isEmpty().
3	Interface	Implements HasErrors.
4	collect(...)	collect(vararg checks) / collect(checks: List<Checked>) combine multiple Checked into one, failing with Invalid.INVALID_VALUE and every pooled error if any input failed.

Exceptions

Sealed exception hierarchy carrying a Checked, for boundaries that only understand exceptions — one subclass per Failed group:

sealed class StatusException(val checked: Checked) : Exception() {
    val status: Status get() = checked.status
    val errors: List<Err> get() = checked.errors

    class RestrictedException(status: Failed.Restricted, errors: List<Err> = emptyList()) : StatusException(...)
    class InvalidException(status: Failed.Invalid, errors: List<Err> = emptyList()) : StatusException(...)
    class RejectedException(status: Failed.Rejected, errors: List<Err> = emptyList()) : StatusException(...)
    class UnservedException(status: Failed.Unserved, errors: List<Err> = emptyList()) : StatusException(...)
}

Exception	Matches
RestrictedException	Failed.Restricted
InvalidException	Failed.Invalid
RejectedException	Failed.Rejected
UnservedException	Failed.Unserved

#	Trait	Details
1	Carries	A Checked, exposed as status: Status and errors: List<Err>.
2	Conversion	Failed.toException(errors) converts a bare Failed status into the matching subclass.
3	Platform equivalents	iOS via @ObjCName in iosMain; JS/TS via jsMain.

Protocols

Maps Status to and from external protocol representations — HTTP and gRPC out of the box, or a custom protocol of your own via CodeLookup.

Type	Purpose
CodesToHttp	Maps Status to/from HTTP status codes.
CodesToGrpc	Maps Status to/from gRPC status codes.
CodeLookup	Interface for defining a mapping to any other protocol.
CompositeLookup	Combines a base CodeLookup with per-code extensions/overrides.

Design

Philosophy

A closed taxonomy keeps generic handling, exhaustive matching, logging, and protocol mappings consistent everywhere a status is used. Codes stay open underneath so each domain can extend the taxonomy freely without forking it. This doesn't replace domain modeling: domain errors explain what happened in one domain, the taxonomy explains what kind of outcome it was, consistently, across every domain in an application. Status is a sealed interface rather than an enum specifically so consumers can add their own codes while still participating in the same taxonomy — an enum can't be extended this way.

Features

#	Feature	Description
1	Status classification	The core Passed/Failed split, with a fixed Group and an open Code beneath it for finer-grained classification.
2	Extensibility	Add domain-specific codes within the same fixed groups, without forking the taxonomy or losing shared meaning.
3	Protocol mappings	Map statuses to and from HTTP, gRPC, or any custom protocol via CodeLookup/CompositeLookup.
4	Validation	Checked, Err, and collect report every problem found at once, instead of stopping at the first.
5	Typed exceptions	StatusException and Failed.toException() for boundaries that only understand exceptions.
6	Result integration	The separate kiit-result module builds a Result<T, E> type on top of this same taxonomy.

Limitations

#	Limitation	Details
1	AI framing is unproven	Stable names and explicit classification are expected to reduce ambiguity for AI tooling, but that's a hypothesis, not a benchmarked result.
2	JS/TS not CI-gated	Exists but isn't CI-gated or published to npm yet; lacks the compiler-enforced exhaustiveness that Kotlin, Java, and Swift (via SKIE) get.

Exclusions

#	Excluded	Reasoning
1	Retry logic or severity levels	Retryability cuts across groups rather than aligning with them — Unserved alone has both retryable and non-retryable codes. A dedicated Retry category was considered and rejected for the same reason.
2	A numeric status code field	An earlier version had one; it invited the wrong inference (looking like an HTTP code while meaning something else). Real protocol numbers are available on demand via CodesToHttp/CodesToGrpc, never implied by the taxonomy itself.
3	A ninth group	Every gRPC code and the most common HTTP codes map onto the existing eight without needing one, tested directly against both.

Tutorial

Status Codes

This walks through building a tiny service that returns Status for expected outcomes, then crosses a boundary that can only communicate via exceptions.

Define a service that returns a Status instead of throwing for expected failures:

import kiit.codes.*

data class User(val id: String, val email: String)

class UserService {
    private val users = mutableMapOf<String, User>()

    fun create(id: String, email: String): Status {
        if (email.isBlank()) return Invalid.BAD_REQUEST
        if (users.containsKey(id)) return Rejected.CONFLICT
        users[id] = User(id, email)
        return Succeeded.CREATED
    }

    fun authorize(id: String, requesterId: String): Status =
        when {
            !users.containsKey(id) -> Rejected.NOT_EXISTS
            id != requesterId -> Restricted.UNAUTHORIZED
            else -> Succeeded.SUCCESS
        }
}

Callers

Call it and branch on the result:

val service = UserService()

val created = service.create("alice", "alice@example.com")
println("${created.name} (success=${created.success})") // CREATED (success=true)

val denied = service.authorize("alice", "bob")
println("${denied.name} (success=${denied.success})") // UNAUTHORIZED (success=false)

Validation

Now add a method that reports every problem at once instead of stopping at the first:

fun UserService.validateSignup(id: String, email: String): Checked {
    val errors = mutableListOf<Err>()
    if (id.isBlank()) errors.add(Err.on("id", id, "Id is required"))
    if (!email.contains("@")) errors.add(Err.on("email", email, "Email must contain @"))
    return if (errors.isEmpty()) Checked.success(Succeeded.SUCCESS)
           else Checked.failure(Invalid.INVALID_VALUE, errors)
}

val checked = service.validateSignup("", "not-an-email")
println("valid=${checked.isValid}, errors=${checked.errors.size}")
// valid=false, errors=2

Checked can only be constructed through Checked.success(status)/Checked.failure(status, errors), so status and errors can never disagree. See Concepts for the full type, or Guide for collect(...) combining multiple Checked results into one.

Try/Catch

Now add a method that throws instead, for a caller that only understands exceptions:

fun UserService.requireAuthorized(id: String, requesterId: String) {
    val status = authorize(id, requesterId)
    if (status is Failed) throw status.toException()
}

try {
    service.requireAuthorized("alice", "bob")
} catch (e: StatusException) {
    println("caught: ${e.status.name} — ${e.message}")
    // caught: UNAUTHORIZED — Not authorized to perform this action
}

status.toException() picked StatusException.RestrictedException automatically, since Restricted.UNAUTHORIZED belongs to the Restricted group. See Concepts for the full exception hierarchy, or Design for why the taxonomy is shaped this way.

Result

kiit-codes classifies an outcome, but doesn't hand back a value alongside it. For that, pair it with kiit-result — a separate Kiit library that builds a Result<T, E> type on this same taxonomy:

fun UserService.find(id: String): Result<User, Status> =
    users[id]?.let { Result.success(it) } ?: Result.failure(Rejected.NOT_EXISTS)

See the kiit-result docs for the full API.

Guide

Usage

Status only, when the outcome itself is enough:

when (val status = authorize(userId, requesterId)) {
    is Passed -> log.info("ok: ${status.name}")
    is Failed -> log.warn("failed: ${status.name} — ${status.message}")
}

Extensibility — custom codes stay inside a built-in group:

val PAYMENT_DECLINED = Failed.Rejected(
    name = "PAYMENT_DECLINED",
    message = "Payment declined",
    origin = "payments",
)

PAYMENT_DECLINED remains a Rejected outcome everywhere in the system while retaining its own domain-specific identity. origin keeps custom namespaces distinct from "kiit" and from other teams' codes.

Validation, reporting every problem instead of stopping at the first:

fun validateUser(name: String, email: String): Checked {
    val errors = mutableListOf<Err>()
    if (name.isBlank()) errors.add(Err.on("name", name, "Name is required"))
    if (!email.contains("@")) errors.add(Err.on("email", email, "Email must contain @"))
    return if (errors.isEmpty()) Checked.success() else Checked.failure(Invalid.INVALID_VALUE, errors)
}

Exceptions, converting a Failed status at a boundary that needs one:

fun requireAuthorized(id: String, requesterId: String) {
    val status = authorize(id, requesterId)
    if (status is Failed) throw status.toException()
}

Protocols

Working code for the types introduced in Concepts — mapping statuses to and from HTTP, gRPC, and a custom protocol of your own.

HTTP, via CodesToHttp:

val http = CodesToHttp()

http.toCode(Succeeded.CREATED)      // 201
http.toCode(Invalid.INVALID_VALUE)  // 400
http.toStatus(404)?.name            // "NOT_FOUND"

gRPC, via CodesToGrpc:

val grpc = CodesToGrpc()

grpc.toCode(Restricted.DENIED)  // 7, PERMISSION_DENIED
grpc.toStatus(6)?.name          // "CONFLICT", ALREADY_EXISTS reversed

Custom protocols, via CodeLookup/CompositeLookup:

val lookup = CompositeLookup(
    base = CodesToHttp(),
    extensions = mapOf(PAYMENT_DECLINED to 402),
)

lookup.toCode(PAYMENT_DECLINED) // 402

FAQ

Common questions about the taxonomy, design choices, alternatives, adoption, and project maturity.

Why

Question	Answer
Why not just use exceptions or booleans?	Exceptions are thrown inconsistently across a codebase, and a boolean can't say why. This gives every outcome a shared shape, closed categories, open codes underneath.
Why a closed taxonomy but open codes?	Closed categories keep generic handling, exhaustive matching, logging, and protocol mappings consistent everywhere. Codes stay open so each domain can extend it freely.
Why classify outcomes if my domain errors already explain what happened?	Domain errors explain what happened in one domain. The taxonomy explains what kind of outcome it was, consistently, across every domain in the app.
Does this replace domain modeling?	No. It classifies outcomes; it doesn't replace aggregates, value objects, or domain events. An infrastructure-level vocabulary, not a competing one.

Alternatives

Question	Answer
How is this different from Arrow's Either/Validated or kotlin-result?	Those give you a Result type with no taxonomy underneath, you supply the meaning yourself. This provides the taxonomy those types can build on, plus a working exception path.
Why not just use raw HTTP status codes everywhere?	A background job or CLI command doesn't have an HTTP status. HTTP was the closest precedent, and the taxonomy is validated against it, but it isn't scoped to HTTP.
Doesn't this lock me into Kiit's taxonomy?	The eight categories are closed and cross-validated against HTTP and gRPC. Every code inside them is yours to extend, and you're free to ignore the built-in ones entirely.

API

Question	Answer
Why not just use strings for status names?	Strings don't give you compiler-checked exhaustiveness, discoverability, or protocol mappings. The goal is consistent classification, not just naming.
Why isn't Status just an enum?	Enums can't be extended by consumers. This lets every application define its own statuses while still participating in the same taxonomy.
Why exactly eight categories?	Every gRPC code and the most common HTTP codes map onto these eight without needing a ninth, tested directly against both.
Why was the numeric status code field removed?	An earlier version had one, and it invited the wrong inference, a number resembling an HTTP code but meaning something else. Real protocol numbers are available on demand, never implied.
Isn't 50+ codes a steep learning curve?	Most of the real cost is the eight categories, not the codes. Each category's default is a safe fallback; the rest is opt-in precision you reach for as needed.
Why is Unserved so much bigger than the others?	Independent evidence, not an oversight, both HTTP and gRPC show the same clustering on their own for capacity and infrastructure failures.
Why isn't retry logic or severity built in?	Retryability cuts across categories rather than aligning with them; Unserved alone has both retryable and non-retryable codes. A dedicated Retry category was considered and rejected.
Doesn't a generic category lose domain-specific detail?	No, the category is deliberately coarse while the code stays domain-specific. PAYMENT_DECLINED and ORDER_CONFLICT can both be Rejected and still keep distinct identities.

Adoption

Question	Answer
What if I classify something incorrectly?	Nothing catastrophic, a status can be moved to a more appropriate category later. The taxonomy improves consistency, it doesn't enforce absolute correctness upfront.
What if my company already has its own status system?	You don't have to replace it overnight. Existing statuses can map into the taxonomy incrementally while keeping their original names and meanings.
How does this work across microservices?	Services don't need identical codes, only the shared categories. Each service keeps its own domain-specific statuses while exposing consistent high-level semantics.

AI

Question	Answer
Is the "built for AI" angle just marketing?	The design decisions are justified on ordinary engineering grounds first, consistency, exhaustive matching, explicit semantics. AI benefits from the same properties, but the library stands on its own without them.
What evidence supports the AI-related claims?	Intentionally modest. Stable names and explicit classification are expected to reduce ambiguity for AI tooling, but that's a hypothesis to validate with real benchmarks, not an assumed result.

Maturity

Question	Answer
Is this production-ready at 1.0.1?	The version reflects the public package's youth, not the underlying design's. The core classification has years of internal production use prior to extraction; newer pieces (JS/TS, iOS) have less track record.
What about single-maintainer risk?	Real risk, worth being upfront about. Apache 2.0 licensed and source available, but there's currently no second maintainer or organizational backing.