Usage Rotation Without Soft Limit

URI: https://docs.ankatech.co/errors/usage-rotation-without-soft-limit
HTTP Status: 422 Unprocessable Content

When you see this

A key's rotation schedule was written turning rotateOnSoftUsageLimit on (from false), and the key's current material has no soft usage limit (softUsageLimit absent or 0). Nothing was stored: the key's schedule is unchanged.

The option rotates the key when its usage count reaches its soft usage limit. A key without one never reaches it, so the option could never act.

A key created or imported with a maximum usage limit and no soft usage limit is given one, floor(0.8 × maxUsageLimit). The only capped key without a derived soft limit is one whose maximum is 1, and an uncapped key has none. A soft limit cleared later by a metadata update leaves none either.

The check runs before the check of the maximum usage limit.

Response Example

{
  "type": "https://docs.ankatech.co/errors/usage-rotation-without-soft-limit",
  "title": "Usage Rotation Without Soft Limit",
  "status": 422,
  "detail": "rotateOnSoftUsageLimit: the key has no soft usage limit, so it can never reach one. Set a soft usage limit on the key first, or send false.",
  "instance": "/api/v3/admin/tenants/550e8400-e29b-41d4-a716-446655440000/keys/payments-data-key/rotation-schedule",
  "timestamp": 1790000000,
  "extensions": {
    "requestId": "9d2f4a61-0c7e-4b35-8e19-2a6b5f3c7d80"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The detail names the option and the remedy, never the key or the tenant.

How to Resolve

1. Set a soft usage limit on the key with the metadata update (PATCH /api/v3/admin/tenants/{tenantId}/keys/{kid}, softUsageLimit strictly below a positive maxUsageLimit), then write the schedule again.
2. Or send rotateOnSoftUsageLimit: false and rotate on exhaustion or on a time-based cadence instead.

An option stored before a later metadata update removed the soft limit is kept: it acts on nothing until the key has a soft limit again.

Operations that emit it

Related Errors

• Usage Rotation Without Usage Limit (422) - the same refusal for rotateOnUsageExhaustion on a key with no maximum usage limit

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