Skip to main content

Errors

The error catalogue is a closed enumeration. Every error code that appears in a KError.code field is catalogued — no per-surface ad-hoc codes, no SDK-layer code-coining. The catalogue is greppable across the codebase and audit ledger by virtue of the closed-taxonomy + SCREAMING_SNAKE_CASE conventions.

The wire shape of KError is bound in conventions §2. This page covers the catalogue's organising principles, family taxonomy, status conventions, lifecycle, and the warning vs error distinction. The full alphabetised lookup with every coined code lives at /specifications/error-catalogue.

1. Organising principles​

1.1 Closed taxonomy​

Adding a new code requires two coordinated steps: (i) coining it in the originating chapter's specification, and (ii) adding a row to the master catalogue at /specifications/error-catalogue. The two-step rule prevents per-surface ad-hoc code coining at the SDK / gateway layer and prevents drift between per-chapter authoritative semantics and the master catalogue.

A code appearing in KError.code without a master-catalogue row is a defect.

1.2 SCREAMING_SNAKE_CASE​

All error codes use SCREAMING_SNAKE_CASE per the conventions enum convention. The closed-taxonomy rule plus the casing convention make the catalogue greppable — every code is a single token a developer can search for across application code, logs, runbooks, and the audit ledger.

1.3 HTTP status conventions per family​

FamilyConventional statusRationale
Resource — not found404Request references a resource that doesn't exist
Resource — conflict409Request conflicts with current state (concurrent-modify, already-exists, in-progress)
Auth — unauthorised401Caller's credentials are invalid or expired
Auth — forbidden / authority insufficient403Authenticated but lacks authority for the requested action
Auth — token expired410Token TTL exceeded; caller should re-issue (distinct from generic 401)
Validation — parse-time400Malformed or violates a declared constraint at parse-time
Validation — semantic422Well-formed but fails a domain-level validation post-authority-check
Capacity — rate limit429Per-period rate limit exceeded
Capacity — tier cap409Tier-bound cap hit (K9O_TIER_CAP_HIT); upgrade rather than retry
Service — unreachable503Upstream dependency unreachable; transient
Service — timeout504Upstream dependency exceeded its TTL
Service — bad gateway502Upstream dependency returned a malformed response
Async readiness425Resource is being prepared (export job, billing snapshot)

The conventions are guidelines, not absolute rules — individual codes may diverge where domain semantics warrant a specific status (e.g., K9O_EXPORT_NOT_SUPPORTED_FOR_MODE is 400 because it's a parse-time policy rejection, not a service-state issue).

1.4 Warning vs error​

Warning codes (§3) ride the success-path meta.warnings envelope and do NOT throw KError. They appear with HTTP status — in the catalogue — they are not errors. Warnings are advisory: the operation succeeded; the platform is signalling a forward-looking concern (deprecated surface, inefficient access pattern, missing index).

2. Error families​

Every code belongs to exactly one family. The family classification drives both the HTTP status convention (§1.3) and the recommended caller-side handling pattern.

FamilyWhat it covers
AuthAuthentication state failures: invalid credentials, MFA required / failed, OTP expired, session expired, magic-link expired, invitation expired, password reset token expired
Authority / RBACPermission and role-check failures: K9O_ACCESS_DENIED, K9O_PII_JOIN_AUTHORITY_INSUFFICIENT, K9O_POLICY_AUTHORING_AUTHORITY_INSUFFICIENT, K9O_BYOK_KEY_PERMISSION_DENIED, K9O_EXTENSION_PERMISSION_DENIED
Resource — not foundResource lookup failures: K9O_COLLECTION_NOT_FOUND, K9O_FUNCTION_NOT_FOUND, K9O_KEY_NOT_FOUND, K9O_BUCKET_NOT_FOUND, K9O_OBJECT_NOT_FOUND, etc.
Resource — conflictConcurrent-modify and state-conflict failures: K9O_CONSTRAINT_VIOLATION, K9O_MIGRATION_CONFLICT, K9O_MULTIPLE_ROWS_RETURNED, K9O_SERIALIZATION_FAILURE, K9O_TRANSACTION_TIMEOUT, K9O_EMAIL_ALREADY_REGISTERED, K9O_KEY_ROTATION_IN_PROGRESS, K9O_EXTENSION_ALREADY_ENABLED
Validation — parse-timeMalformed input rejected at parse / declaration layer: K9O_WEAK_PASSWORD, K9O_INVALID_VECTOR_DIMENSION, K9O_INVALID_FILTER, K9O_INVALID_MIGRATION_FILE, K9O_CIRCULAR_REFERENCE_DETECTED, K9O_POLICY_NESTING_TOO_DEEP, K9O_INJECTION_DETECTED
Validation — semanticWell-formed input failing domain validation post-authority-check: K9O_APPROVAL_POLICY_NOT_MATCHED, K9O_POLICY_BUNDLE_INVALID, K9O_GATE_CONSTRAINT_VIOLATION, K9O_GATE_TOKEN_INVALID, K9O_GATE_REJECTED, K9O_FUNCTION_DEPLOYMENT_FAILED, K9O_MALWARE_DETECTED, K9O_LEDGER_VERIFICATION_FAILED
Auth — token expiryToken-TTL-exceeded failures distinct from generic 401: K9O_OTP_EXPIRED, K9O_MAGIC_LINK_EXPIRED, K9O_PASSWORD_RESET_TOKEN_EXPIRED, K9O_INVITATION_EXPIRED
CapacityCaps and rate-limits: K9O_SUBSCRIPTION_LIMIT_EXCEEDED, K9O_TIER_CAP_HIT, K9O_EGRESS_QUOTA_EXCEEDED, K9O_DISCOVERY_RATE_LIMITED
Approval / Maker-CheckerApproval-flow failures: K9O_APPROVAL_DELEGATION_TRANSITIVE_PROHIBITED, K9O_APPROVAL_DELEGATION_SCOPE_EXCEEDED, K9O_BULK_APPROVAL_AUTHORITY_INSUFFICIENT
Service — unreachable / timeout / bad gatewayUpstream dependency failures: K9O_BYOK_KEY_UNREACHABLE, K9O_HYOK_CLUSTER_UNREACHABLE, K9O_IDENTITY_PROVIDER_UNREACHABLE, K9O_SIEM_WEBHOOK_UNREACHABLE, K9O_IDP_FEDERATION_FAILED, K9O_EXTENSION_HOOK_DELIVERY_FAILED, K9O_FUNCTION_TIMEOUT, K9O_FUNCTION_MEMORY_EXCEEDED
LifecycleResource-lifecycle conflicts: K9O_PROJECT_SOFT_DELETED, K9O_EXTENSION_PURGE_GATE_REQUIRED, K9O_BILLING_EXPORT_NOT_READY, K9O_CROSS_SHARD_TRANSACTION_UNSUPPORTED, K9O_CUSTODY_MISMATCH

The family-to-code mapping is not exclusive at the conceptual level — some codes cross-classify into multiple families (e.g., K9O_APPROVAL_POLICY_NOT_MATCHED involves both approval workflow and semantic validation). The master catalogue assigns each code to exactly one canonical family for routing purposes.

3. Warnings​

Warnings ride the success-path meta.warnings envelope per the conventions envelope shape. Each warning is an array entry of shape { code, message } on a successful response.

CodeFamilyDescription
captchaRequiredCapacityAnonymous-surface sustained-abuse pattern triggered gateway-side CAPTCHA progressive challenge; next request must include X-Captcha-Token: <token> from platform-issued CAPTCHA flow
K9O_COUNT_MODE_DOWNGRADEDPaginationServer downgraded the requested count mode (e.g., exact → estimated due to per-tier policy or runtime cost)
K9O_DEPRECATED_SURFACEVersioningCaller used a deprecated SDK surface; the recommendation cites the replacement
K9O_OFFSET_PAGINATION_INEFFICIENTPaginationCaller is using .range() for pagination on a large collection; cursor-based pagination is recommended
K9O_POLICY_NOT_COUPLEDPolicySchema-only migration without an accompanying policy section
query_limit_clampedPaginationCaller-requested limit clamped to per-endpoint maximum; result correctness is unaffected; adjust the request limit if needed
result_count_cappedPaginationResponse set truncated at platform-imposed maximum; meta.totalCount reflects the cap value; refine the query or accept the cap
K9O_TEXT_SEARCH_NO_INDEXIndexFull-text query executed without a GIN index
K9O_VECTOR_SEARCH_NO_INDEXIndexVector search executed without an ivfflat / hnsw index

The warning catalogue is closed with the same two-step coining rule as the error catalogue.

4. Error code lifecycle​

4.1 Adding a code​

The originating chapter is the authoritative source for the code's semantics (when it fires, what context fields it carries, what the recommendation shape is). Adding a code requires:

  1. Coining it in the originating chapter's specification.
  2. Adding the master row to /specifications/error-catalogue (HTTP status, family, originating chapter).
  3. A test that validates the code fires when its trigger condition is met.

4.2 Deprecating a code​

A code may be deprecated — kept in the catalogue but no longer fired by new code paths — per the conventions deprecation surface. The catalogue carries the deprecation notice alongside the row; callers matching on the code continue to receive it from legacy paths until the deprecation period ends.

4.3 Removing a code​

A code is removed from the catalogue only after every code path that fires it has been removed. Removal without code-path-removal is a defect (the caller-visible code still fires; the catalogue silently lacks the row).

4.4 Renaming a code​

Code names are immutable from coining. A code-name change is a remove-and-add: deprecate the old name; add the new name; the standard deprecation period applies.

5. See also​

  • /specifications/error-catalogue — the full alphabetised lookup of every coined error code with HTTP status, family, and originating chapter.
  • Conventions — the KError wire shape (code, message, context, recommendation).