Skip to main content

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
}
FieldTypeNotes
codestring (SCREAMING_SNAKE_CASE)Drawn from a closed taxonomy. Add a new code by amendment, not by extemporising.
messagestringHuman-readable; safe to log; safe to surface.
contextobjectFamily-specific structured fields — previousRequestHash on K9O_IDEMPOTENCY_KEY_COLLISION, layer: "edge" on K9O_INJECTION_DETECTED.
recommendationtext | nullOptional 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:

FamilyExamplesHTTP
ValidationK9O_INVALID_REQUEST_SHAPE, K9O_MISSING_REQUIRED_FIELD, K9O_INVALID_FIELD_VALUE400
AuthK9O_UNAUTHENTICATED, K9O_INVALID_TOKEN, K9O_TOKEN_EXPIRED401
AuthorisationK9O_ACCESS_DENIED, K9O_PROJECT_SCOPE_MISMATCH, K9O_STEP_UP_REQUIRED403
ResourceK9O_NOT_FOUND, K9O_ALREADY_EXISTS, K9O_STATE_CONFLICT404 / 409
Tier / capacityK9O_TIER_CAP_HIT, K9O_TIER_RATE_LIMIT_EXCEEDED, K9O_POOL_EXHAUSTED409 / 429
IdempotencyK9O_IDEMPOTENCY_KEY_COLLISION409
Anti-injectionK9O_INJECTION_DETECTED400
Shard / dataK9O_CROSS_SHARD_TRANSACTION_UNSUPPORTED422
CustodyK9O_CUSTODY_MISMATCH409
Gate (irreversible action)K9O_GATE_REQUIRED, K9O_GATE_REJECTED, K9O_GATE_TOKEN_INVALID, K9O_GATE_TOKEN_EXPIRED, K9O_GATE_ALREADY_REDEEMED403 / 409 / 422
ServerK9O_INTERNAL_ERROR, K9O_UPSTREAM_UNAVAILABLE5xx

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-After header.
  • 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.