> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> Shared error codes for all Tenant KMS endpoints.

## Error reference

Tenant KMS endpoints return errors in one of two shapes. The **onboard** and **probe** failures return a human-readable message in `error` (with an optional `details` field):

```json theme={"dark"}
{ "error": "KMS access denied. Check that the IAM/RBAC grant gives KnoxCall both Encrypt and Decrypt on this key.", "details": "..." }
```

The **unseal** and **rotate** endpoints return a machine-readable code in `error` plus a `message`:

```json theme={"dark"}
{ "error": "not_sealed", "message": "Tenant is not currently sealed" }
```

This table is non-exhaustive — it lists the common failures. Validation errors (missing `provider`, `kms_key_ref`, malformed `config`) also return `400` with a descriptive `error` message.

### Onboard / probe failures (`POST /admin/tenant-kms`)

These return `{ error: "<message>", details?: "<string>" }`.

| Status | `error` message                                                                                         | Meaning                                                                                                                                                                     |
| ------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `KMS access denied. Check that the IAM/RBAC grant gives KnoxCall both Encrypt and Decrypt on this key.` | The probe encrypt/decrypt round-trip was denied by your KMS IAM/RBAC policy                                                                                                 |
| `400`  | `Field "<name>" is not permitted in tenant KMS config. ...`                                             | `config` contained a blocked static-credential field (access key, secret key, client secret, private key, service-account key, etc.) — use STS/WIF/SA-impersonation instead |
| `400`  | `KMS probe roundtrip mismatch — refusing to onboard a key we cannot reliably decrypt with.`             | The wrap+unwrap probe did not return the original plaintext                                                                                                                 |
| `400`  | `KMS probe failed.`                                                                                     | The probe failed for another reason (see `details`)                                                                                                                         |
| `401`  | `authentication required`                                                                               | No authenticated session                                                                                                                                                    |
| `400`  | `X-Tenant-ID header required`                                                                           | `X-Tenant-ID` header missing                                                                                                                                                |
| `403`  | `<reason>`                                                                                              | Caller is not an owner/admin of the tenant                                                                                                                                  |
| `500`  | `Failed to persist BYOK configuration.`                                                                 | The configuration probe passed but persisting it failed (see `details`)                                                                                                     |
| `502`  | `KMS provider unreachable during probe. Try again in a minute.`                                         | KnoxCall could not reach the KMS provider during the probe                                                                                                                  |

### Step-up required (`POST /admin/tenant-kms/unseal`, `POST /admin/tenant-kms/rotate`)

These endpoints require a recent step-up verification. When one is missing or expired:

| Status | Response                                                                                                                | Meaning                                                                                                                                     |
| ------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | `{ "error": "Recent step-up verification required for this action", "requires_step_up": true, "max_age_minutes": <n> }` | Re-verify step-up (e.g. `POST /auth/2fa/verify-step-up` or `POST /auth/passkey/verify-step-up`) within the last `max_age_minutes` and retry |

### Unseal / rotate failures

These return `{ error: "<code>", message: "<string>" }`.

| Status | Code                      | Meaning                                                                                            |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------------- |
| `404`  | `no_kms_config`           | No customer KMS configured for this tenant (unseal only)                                           |
| `404`  | `no_active_key`           | No active master key found — required for rotation                                                 |
| `409`  | `not_sealed`              | Tenant is not currently sealed (unseal only)                                                       |
| `409`  | `sealed`                  | Cannot rotate while sealed — unseal first                                                          |
| `500`  | `provider_resolve_failed` | KMS provider could not be constructed from the stored config (unseal)                              |
| `500`  | `provision_failed`        | Provisioning a new tenant master key failed (rotate)                                               |
| `502`  | `unseal_failed`           | Unseal roundtrip failed — KMS still unreachable or access still denied (includes a `reason` field) |