Skip to content

kiit.codes

Jump to bottom
kishore edited this page May 26, 2026 · 5 revisions

Status Codes

Status is a platform-agnostic status type that lives in src/lib/codes/. It describes the status of any operation — a service call, a background job step, using a consistent shape rather than throwing raw errors or returning ad-hoc booleans.

Example

Sample JSON representation, which can be used as ApiError response.

{
    "name" : "TOKEN_EXPIRED",
    "type" : "denied" // denied | ignored | invalid | errored | unknown
    "code" : 403,
    "success": false,
    "message": "Session token expired"
}

Hierarchy

Logical heirarchy and relationship of the status types.

  1. Status = Passed | Failed
  2. Passed = Succeeded | Pending | Filtered | Ignored
  3. Failed = Denied | Invalid | Errored | Unknown
graph TD
    classDef statusNode    fill:#3b82f6,stroke:#1d4ed8,color:#ffffff,font-weight:bold
    classDef passedNode    fill:#86efac,stroke:#16a34a,color:#14532d,font-weight:bold
    classDef succeededNode fill:#22c55e,stroke:#15803d,color:#ffffff,font-weight:bold
    classDef pendingNode   fill:#fde047,stroke:#ca8a04,color:#713f12,font-weight:bold
    classDef filteredNode  fill:#9ca3af,stroke:#6b7280,color:#ffffff,font-weight:bold
    classDef ignoredNode   fill:#9ca3af,stroke:#6b7280,color:#ffffff,font-weight:bold
    classDef failedNode    fill:#fca5a5,stroke:#f87171,color:#7f1d1d,font-weight:bold
    classDef deniedNode    fill:#111827,stroke:#000000,color:#ffffff,font-weight:bold
    classDef invalidNode   fill:#f97316,stroke:#c2410c,color:#ffffff,font-weight:bold
    classDef erroredNode   fill:#dc2626,stroke:#b91c1c,color:#ffffff,font-weight:bold
    classDef unknownNode   fill:#7f1d1d,stroke:#450a0a,color:#ffffff,font-weight:bold

    Status["Status<br/>name / type / code<br/>message / success"]

    Passed["Passed<br/>success: true"]
    Failed["Failed<br/>success: false"]

    Succeeded["Succeeded<br/>type: succeeded"]
    Pending["Pending<br/>type: pending"]
    Filtered["Filtered<br/>type: filtered"]
    Ignored["Ignored<br/>type: ignored"]
    

    Denied["Denied<br/>type: denied"]
    Invalid["Invalid<br/>type: invalid"]
    Errored["Errored<br/>type: errored"]
    Unknown["Unknown<br/>type: unknown"]

    Status --> Passed
    Status --> Failed
    Passed --> Succeeded
    Passed --> Pending
    Passed --> Filtered
    Passed --> Ignored
    Failed --> Denied
    Failed --> Invalid
    Failed --> Errored
    Failed --> Unknown

    class Status statusNode
    class Passed passedNode
    class Succeeded succeededNode
    class Pending pendingNode
    class Failed failedNode
    class Denied deniedNode
    class Ignored ignoredNode
    class Invalid invalidNode
    class Errored erroredNode
    class Unknown unknownNode
Loading

Purpose

Three problems this solves:

  1. Universal: Can be used universally in service layers ( XService.ts ), background jobs, routes.
  2. Hierarchy: Status has a logical group and heirarchy for successes and failures.
  3. Standard : Establishes an precise status type and representation across layers.
  4. Compliant: Convertible to Http status codes via toHttpStatus() in src/lib/codes/utils.ts
  5. Reusable : Can be reused across multiple operations that can yield the same status/error.
  6. Extensible: Easily extensible by creating new Status Codes for specific domains / features.
  7. Searchable: The name and type are unique and easily searchable in logs.
  8. Aggregated: Because of the hierarchy, the type, or name can be aggregated in logs/records.
  9. Exceptions: Compatible with exceptions via the StatusError subtype of Error to store it.

Related

Similar definitions exist else where. GraphQL The closest representation of this is MutationError https://cosmo.wundergraph.com/4f7ac3fd/staging/graph/main/schema?category=interfaces&typename=MutationError&fieldName=

{
    code: number,
    message: string
}

Grouping

Parent Type Level Purpose
Status Passed Parent Parent of successes
Passed Succeeded Child Successful operation
Passed Pending Child Pending processing
Passed Filtered Child Filtered from processing
Passed Ignored Child Processed but ignored
Status Failed Parent Parent for any failure
Failed Denied Child Security related
Failed Invalid Child Invalid data
Failed Errored Child Failure of known business rule
Failed Unknown Child Unhandled failure

Shape

Every Status has the following fields and carries the info:

Field Purpose
type Discriminant of ('denied', 'invalid', 'ignored', 'errored', 'unknown', )
name Unique domain label of status, e.g. TOKEN_EXPIRED, RATE_LIMITED, both are Denied
code Numeric code — defaults align with HTTP status codes, flexible for other runtimes
message Human-readable description — must be a constant, never constructed from runtime data
success Boolean shortcut for callers that don't need to narrow the type

Clone this wiki locally