Skip to content

Key Protection Backend Misconfigured

URI: https://docs.ankatech.co/errors/key-protection-backend-misconfigured HTTP Status: 503 Service Unavailable

When you see this

The backend that protects key material is configured, but is not usable as configured. The operation was refused before anything was written — no key material was persisted and no partial state was left behind.

This response deliberately carries no Retry-After header, and that omission is the whole point of the distinction from Key Protection Backend Unavailable. Retrying re-presents the same broken configuration, and for a wrong hardware-module PIN each retry consumes an authentication attempt — enough of them lock the credential. A client that honours Retry-After would therefore have driven exactly the lockout the platform's guards exist to prevent.

Common Causes

  • A credential for the backend is present but wrong, expired, or lacks the required permission.
  • The stored key material references a different key-encryption key than the one this deployment resolves — for example after a tenant was moved to a different backend while earlier material still exists.
  • A required coordinate (region, vault, key name, module path) is absent or points somewhere that cannot serve this deployment.
  • The hardware-module library was initialized with a threading contract weaker than this operation requires. That contract is fixed for the life of the server process, so it cannot change until the deployment is restarted with a consistent configuration — which is why this condition arrives here, under the status that tells you not to wait, rather than under the retryable sibling.

These causes are deliberately indistinguishable from the outside. Every one of them returns the same status and the same body — no coordinate, credential, module or policy is named. Telling them apart from a response would let a caller map the deployment's key-protection topology by trial. The server-side entry for your correlationId names which one fired; a client cannot, and should not branch as though it could.

How to Resolve

  1. Do not retry on a timer, and do not build automatic retry into a client for this status. Nothing about the condition changes between attempts.
  2. Report it to whoever operates the deployment, quoting the correlationId from the response body.
  3. An operator resolves it by correcting the backend configuration — the server-side entry for that correlationId names which condition fired.

503 without Retry-After is intentional. The status says the service cannot serve the request; the absent header says waiting will not change that. Treat it as requiring human action, not backoff.