Applications need to communicate a simple idea consistently: what happened?

In practice, success and failure are often modeled differently across domains, application layers, protocols, and error-handling approaches. This creates several recurring problems:

kiit-codes provides a shared application-level model for these concerns.

A fixed taxonomy provides consistent classification, extensible codes preserve domain-specific meaning, and protocol mappings keep application outcomes independent from their transport. The same model can then be used across statuses, validation, exceptions, and result types.

Gradle (Kotlin DSL):

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

A status can represent an outcome without requiring exceptions or a result type:

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}")
}

Built-in codes expose stable fields suitable for application logic, logging, APIs, and diagnostics:

{
    "name"    : "CONFLICT",
    "group"   : "Rejected",
    "origin"  : "kiit",
    "success" : false,
    "message" : "The request conflicts with the current state"
}

Codes uses a three-tier model:

Status → Group → Code

Status and Group are fixed so applications share the same high-level meaning. Code is open: Kiit supplies common defaults while applications can add their own domain-specific codes.

The two statuses are:

• Passed — Succeeded, Pending, Excluded, Information
• Failed — Restricted, Invalid, Rejected, Unserved

Each code provides an id, name, group, origin, message, and success flag. Built-in codes use the kiit origin and each group has a default code for cases where more precision is unnecessary.

The built-in taxonomy contains common application outcomes such as SUCCESS, CREATED, DENIED, INVALID_VALUE, CONFLICT, TIMEOUT, and UNEXPECTED.

The taxonomy stays consistent while codes remain open to your domain.

Custom codes use the same group types as Kiit's defaults:

import kiit.codes.Failed

// Example custom code
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 domain-specific identity. The origin keeps custom namespaces distinct from Kiit and from other modules or teams.

Application outcomes should describe what happened, independently of how they are transported.

Kiit codes can be mapped to protocol-specific representations at system boundaries.

CodesToHttp maps statuses to HTTP codes using group defaults plus specific overrides where needed.

import kiit.codes.*

val http = CodesToHttp()

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

Reverse conversion is deterministic but can be lossy because multiple application codes may map to the same HTTP status.

CodesToGrpc follows the same model and covers all gRPC status codes.

import kiit.codes.*

val grpc = CodesToGrpc()

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

The mapping abstraction is not limited to HTTP and gRPC. CodeLookup and CompositeLookup can be used to define or extend mappings for other protocols.

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

lookup.toCode(PAYMENT_DECLINED) // 402

Codes is designed to work at different application boundaries without requiring one error-handling style.

Use Status when the outcome itself is enough.

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}")
}

kiit-codes has been extracted from kiit framework and polished as a standalone module. This has been used in production for over 4+ years to power mobile and server kotlin applications. Current work is focused on the Kotlin release, documentation, examples, and ecosystem integration.

See GitHub Issues for current work and discussions.

• Kotlin Multiplatform
• JVM, Android, iOS (simulator, iosArm64, x64)
• No external runtime dependencies

Contributions and design feedback are welcome. See BUILD.md for build, test, and publish instructions.

Apache License 2.0