Handling Errors
Kilimanjaro returns a uniform KError envelope on every failure and a closed taxonomy of error codes. This page covers the conceptual shape; the conventions reference carries the binding wire shape and the error catalogue carries the full per-code enumeration.
The envelope
Every error is a KError:
{
"code": "STRING",
"message": "human-readable",
"context": { /* family-specific structured fields */ },
"recommendation": null // or remediation text when present
}
| Field | Type | Notes |
|---|---|---|
code | string (SCREAMING_SNAKE_CASE) | Drawn from a closed taxonomy. Add a new code by amendment, not by extemporising. |
message | string | Human-readable; safe to log; safe to surface. |
context | object | Family-specific structured fields — previousRequestHash on K9O_IDEMPOTENCY_KEY_COLLISION, layer: "edge" on K9O_INJECTION_DETECTED. |
recommendation | text | null | Optional remediation hint: text when present, null on most errors. |
The four fields are universal. Family-specific extensions live inside context; they never extend the top-level shape. The request id (req_<base62>) is carried in meta.context.requestId on success and as a response header (X-K9o-Request-Id) on every response, so error correlation does not depend on the error body shape.
The closed-taxonomy rule
code is drawn from a closed taxonomy. Implementations may not coin private codes. A consumer that reads code, switches on its known family, and falls through to a generic handler for unknown codes handles every error the platform throws.
Universal families
Every surface introduces family-specific codes. The universal families that any endpoint may throw:
| Family | Examples | HTTP |
|---|---|---|
| Validation | K9O_INVALID_REQUEST_SHAPE, K9O_MISSING_REQUIRED_FIELD, K9O_INVALID_FIELD_VALUE | 400 |
| Auth | K9O_UNAUTHENTICATED, K9O_INVALID_TOKEN, K9O_TOKEN_EXPIRED | 401 |
| Authorisation | K9O_ACCESS_DENIED, K9O_PROJECT_SCOPE_MISMATCH, K9O_STEP_UP_REQUIRED | 403 |
| Resource | K9O_NOT_FOUND, K9O_ALREADY_EXISTS, K9O_STATE_CONFLICT | 404 / 409 |
| Tier / capacity | K9O_TIER_CAP_HIT, K9O_TIER_RATE_LIMIT_EXCEEDED, K9O_POOL_EXHAUSTED | 409 / 429 |
| Idempotency | K9O_IDEMPOTENCY_KEY_COLLISION | 409 |
| Anti-injection | K9O_INJECTION_DETECTED | 400 |
| Shard / data | K9O_CROSS_SHARD_TRANSACTION_UNSUPPORTED | 422 |
| Custody | K9O_CUSTODY_MISMATCH | 409 |
| Gate (irreversible action) | K9O_GATE_REQUIRED, K9O_GATE_REJECTED, K9O_GATE_TOKEN_INVALID, K9O_GATE_TOKEN_EXPIRED, K9O_GATE_ALREADY_REDEEMED | 403 / 409 / 422 |
| Server | K9O_INTERNAL_ERROR, K9O_UPSTREAM_UNAVAILABLE | 5xx |
K9O_ACCESS_DENIED is the single canonical authority-insufficient code — the older FORBIDDEN / POLICY_DENY / RBAC_DENY / ABAC_DENY spellings are non-canonical synonyms and are not thrown. Most errors carry no recommendation; where one is set, it is text.
Retry guidance
The SDK auto-retries by default:
- 5xx server errors with exponential backoff and full jitter.
- 429 capacity errors honouring the
Retry-Afterheader. - Network errors (connection reset, DNS failure, request timeout).
The SDK does not auto-retry:
- 4xx (except 429). Validation, auth, authorisation, resource, idempotency-collision, custody errors. These are caller-actionable; auto-retry masks the bug.
- 409
K9O_TIER_CAP_HIT. Retrying does not help; the cap resets at the end of its period, or the plan is upgraded.
Default policy: base delay 100 ms, multiplier 2.0, full jitter, max 5 attempts, max 30 s wall-clock. Override via RetryConfig on the client constructor or per call. See conventions §7 for the full shape.
Rate-limit behaviour
Capacity errors return HTTP 429 with one of two codes:
K9O_TIER_RATE_LIMIT_EXCEEDED— the calling project's per-window quota is exhausted.K9O_POOL_EXHAUSTED— a shared resource pool (e.g., connection pool, function warm-pool) is at capacity.
Both carry Retry-After in seconds, both surface the wait in the KError, and both are auto-retried by the SDK with the server-supplied delay overriding the computed backoff.
Idempotency-collision semantics
The platform follows replay-with-strict-match. When the same idempotency key is presented within the 24-hour TTL with a different request body, the platform throws K9O_IDEMPOTENCY_KEY_COLLISION rather than silently replaying the cached response. context carries previousRequestHash, currentRequestHash, and previousResponseTimestamp for the caller to diagnose. The full behaviour matrix is in conventions §7.5.