Skip to content

Key Material Usage Exhausted

URI: https://docs.ankatech.co/errors/key-material-usage-exhausted
HTTP Status: 409 Conflict

When you see this

A request asked a key to apply protection — to encrypt, to sign, or to be the target of a re-encryption or a re-signature — and the key's current material has used up its usage limit (maxUsageLimit). Nothing was encrypted or signed, and nothing was counted or written.

The key itself is not changed by the refusal: it keeps its status and its current material, and everything it already protected still decrypts and verifies. Rotating the key gives it a new current material whose usage count starts at zero.

What the usage limit counts

The usage limit is a protection budget. One use is counted for each operation that applies protection with the key, for simple, composite and stateful keys alike — a composite key counts one use per operation, never one per component:

  • a signature: one use for the signing key;
  • an encryption: one use for each key the result is newly encrypted to;
  • a sign-then-encrypt: one use for the signing key and one for the recipient key;
  • a re-encryption or a re-signature: one use for the target key (newKid), none for the source key;
  • a re-encryption of a multi-recipient token: also one use for each recipient key it keeps, because the result is encrypted to that key again under a new content-encryption key; a kept recipient whose usage limit is used up refuses the re-encryption with this problem, like the target;
  • a PKCS#7 conversion: one use for each signer and each recipient key.

Decrypting and verifying are never counted. A use is counted before any output exists, and an operation that fails after it was admitted keeps its use. When the last use is contended, exactly as many requests succeed as uses remain, on any number of service instances; the others receive this problem.

An encryption made outside the platform with an exported public key is not seen by the platform and is not counted. For a key whose public key is exported for encryption, the expiry is the bound that holds.

Common Causes

  • Every use of the budget has been spent. The key's usageCount has reached its maxUsageLimit.
  • The request lost the race for the last use. Another request was counted first.

A key whose expiry has also passed is answered with Key Material Expired instead.

Response Example

{
  "type": "https://docs.ankatech.co/errors/key-material-usage-exhausted",
  "title": "Key Material Usage Exhausted",
  "status": 409,
  "detail": "Operation 'sign' is refused: the key's current material has reached its usage limit. Rotate the key to protect new data; what it already protected can still be decrypted and verified.",
  "instance": "/api/v3/crypto/sign",
  "correlationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "timestamp": 1768472400,
  "extensions": {
    "code": "KEY_MATERIAL_USAGE_EXHAUSTED"
  }
}

The detail names the refused operation (encrypt or sign) and never the key or its count. On a PKCS#7 conversion the refused signer or recipient is named under extensions.actor (index, role, leg), never by its key.

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. There is no Retry-After: retrying cannot succeed.

Where it is answered

The same operations as Key Material Expired: every operation that applies protection with a tenant key, on the buffered, streaming and PKCS#7 conversion routes, judged on the target key of a re-encryption or a re-signature and never on its source. On a streaming operation the refusal is decided before any output exists.

Each refusal is recorded in the audit trail as a signed crypto operation with status DENIED and error code DENY_KEY_MATERIAL_USAGE_EXHAUSTED, naming the refused key and its material version.

How to Resolve

  1. Rotate the key. The new current material starts at a usage count of zero, with the usage limit the rotation states or carries forward. The exhausted material becomes RETIRED and keeps decrypting and verifying what it protected.
  2. Do not try to raise the limit. Once reached, a usage limit is final: a key-metadata update that sets or clears maxUsageLimit on an exhausted key is refused with Key Protection Limit Reached. Before the limit is reached it can be raised, as long as the new value stays above the uses already counted.
  3. Watch the soft limit. A softUsageLimit below the maximum warns ahead of the hard limit, so the rotation can happen before any request is refused. Reaching either limit records a signed alert in the tenant's audit trail and e-mails the key's administrators.
  4. Let the key rotate itself. The key's rotation schedule can rotate it when it reaches its soft limit (rotateOnSoftUsageLimit) or its maximum (rotateOnUsageExhaustion), while automatic rotation is enabled — see Rotation on key usage*.

Standards basis

KMIP limits usage counts to operations that apply protection and leaves processing unlimited (KMIP 2.1 §4.59); NIST SP 800-57 Part 1 Rev. 5 ends a key's originator-usage period while its recipient-usage period continues (§5.3.5, §5.3.6). See NIST SP 800-57 Part 1 Rev. 5 and the KMIP Specification 2.1.

Related: Key Material Expired — the same refusal for a reached expiry; Key Protection Limit Reached — the metadata update refused once a limit is reached; Stateful Key Exhausted — a stateful signature key with no one-time signature left, a different limit.

* restricted content — see higher-tier documentation