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
| Family | Conventional status | Rationale |
|---|---|---|
| Resource — not found | 404 | Request references a resource that doesn't exist |
| Resource — conflict | 409 | Request conflicts with current state (concurrent-modify, already-exists, in-progress) |
| Auth — unauthorised | 401 | Caller's credentials are invalid or expired |
| Auth — forbidden / authority insufficient | 403 | Authenticated but lacks authority for the requested action |
| Auth — token expired | 410 | Token TTL exceeded; caller should re-issue (distinct from generic 401) |
| Validation — parse-time | 400 | Malformed or violates a declared constraint at parse-time |
| Validation — semantic | 422 | Well-formed but fails a domain-level validation post-authority-check |
| Capacity — rate limit | 429 | Per-period rate limit exceeded |
| Capacity — tier cap | 409 | Tier-bound cap hit (K9O_TIER_CAP_HIT); upgrade rather than retry |
| Service — unreachable | 503 | Upstream dependency unreachable; transient |
| Service — timeout | 504 | Upstream dependency exceeded its TTL |
| Service — bad gateway | 502 | Upstream dependency returned a malformed response |
| Async readiness | 425 | Resource 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.
| Family | What it covers |
|---|---|
| Auth | Authentication state failures: invalid credentials, MFA required / failed, OTP expired, session expired, magic-link expired, invitation expired, password reset token expired |
| Authority / RBAC | Permission 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 found | Resource lookup failures: K9O_COLLECTION_NOT_FOUND, K9O_FUNCTION_NOT_FOUND, K9O_KEY_NOT_FOUND, K9O_BUCKET_NOT_FOUND, K9O_OBJECT_NOT_FOUND, etc. |
| Resource — conflict | Concurrent-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-time | Malformed 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 — semantic | Well-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 expiry | Token-TTL-exceeded failures distinct from generic 401: K9O_OTP_EXPIRED, K9O_MAGIC_LINK_EXPIRED, K9O_PASSWORD_RESET_TOKEN_EXPIRED, K9O_INVITATION_EXPIRED |
| Capacity | Caps and rate-limits: K9O_SUBSCRIPTION_LIMIT_EXCEEDED, K9O_TIER_CAP_HIT, K9O_EGRESS_QUOTA_EXCEEDED, K9O_DISCOVERY_RATE_LIMITED |
| Approval / Maker-Checker | Approval-flow failures: K9O_APPROVAL_DELEGATION_TRANSITIVE_PROHIBITED, K9O_APPROVAL_DELEGATION_SCOPE_EXCEEDED, K9O_BULK_APPROVAL_AUTHORITY_INSUFFICIENT |
| Service — unreachable / timeout / bad gateway | Upstream 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 |
| Lifecycle | Resource-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.
| Code | Family | Description |
|---|---|---|
captchaRequired | Capacity | Anonymous-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_DOWNGRADED | Pagination | Server downgraded the requested count mode (e.g., exact → estimated due to per-tier policy or runtime cost) |
K9O_DEPRECATED_SURFACE | Versioning | Caller used a deprecated SDK surface; the recommendation cites the replacement |
K9O_OFFSET_PAGINATION_INEFFICIENT | Pagination | Caller is using .range() for pagination on a large collection; cursor-based pagination is recommended |
K9O_POLICY_NOT_COUPLED | Policy | Schema-only migration without an accompanying policy section |
query_limit_clamped | Pagination | Caller-requested limit clamped to per-endpoint maximum; result correctness is unaffected; adjust the request limit if needed |
result_count_capped | Pagination | Response set truncated at platform-imposed maximum; meta.totalCount reflects the cap value; refine the query or accept the cap |
K9O_TEXT_SEARCH_NO_INDEX | Index | Full-text query executed without a GIN index |
K9O_VECTOR_SEARCH_NO_INDEX | Index | Vector 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:
- Coining it in the originating chapter's specification.
- Adding the master row to
/specifications/error-catalogue(HTTP status, family, originating chapter). - 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
KErrorwire shape (code,message,context,recommendation).