Skip to content

Custody Material Unreadable

URI: https://docs.ankatech.co/errors/custody-material-unreadable
HTTP Status: 409 Conflict

When you see this

An online re-wrap step (a key-encryption key rotation, a compromise re-key, or a move to another key under the same provider account and credential) met a key whose wrapped private key the tenant's own key-encryption keys refuse to unwrap: the stored copy is damaged, fails its authentication tag, or names a key-encryption key that is not in the tenant's lineage. Every other key of the step was re-wrapped; that key was not.

The key stays under the previous key-encryption key version, so that version never reaches the zero count that retires it, and nothing is destroyed. A backend that is unavailable or throttled is not this problem: it answers its own retryable 503 and the step is asked again.

This problem is answered by the key service to the platform's own administration service while it drives a key custody move, one bounded re-wrap step per call. It is never answered to a browser, an SDK or an API client, so its instance names an internal call and is not reproduced here. An operator sees its effect on the move instead: the move does not complete, the tenant stays active, and the step is asked again every 15 minutes until the key is dealt with; the move is never failed, because an online move only goes forward.

Response Example

{
  "type": "https://docs.ankatech.co/errors/custody-material-unreadable",
  "title": "Custody Material Unreadable",
  "status": 409,
  "detail": "A key could not be unwrapped under the tenant's key-encryption keys; it was not re-wrapped.",
  "correlationId": "6a0c2f9e-3d71-4b58-8e24-c1f5a7d9b036",
  "timestamp": 1793696400
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The detail is fixed: it names no tenant, key, key-encryption key or count.

How to Resolve

  1. Find the key in the key service's log: the warning Online custody re-wrap could not unwrap a key under the tenant's lineage names the tenant and the key material.
  2. Confirm whether the key can still be used: a key whose stored copy cannot be unwrapped cannot decrypt or sign either. Restore it from a backup of the tenant's database if one holds a readable copy, or destroy the key version through its lifecycle if its data no longer needs it.
  3. Nothing needs to be restarted. The key that was not re-wrapped is the only one left under the previous version; the next attempt re-wraps it once it is readable, or finds it destroyed, and the previous version then retires.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.