Skip to content

Capability Grant Re-pin Refused

URI: https://docs.ankatech.co/errors/capability-grant-repin-refused
HTTP Status: 409 Conflict

When you see this

You asked to re-pin a Capability Grant to another Constraint Policy version, replaceCapabilityGrantPolicyVersion (PUT /api/v3/admin/tenants/{tenantId}/capability-grants/{grantId}/policy-version), and the re-pin was refused. Nothing changed: the grant keeps its current pin, and no assignment is added to its history.

The cause travels as the reason extension member. Each reason is a property of the grant or of the requested version, so a retry of the same request is refused the same way.

reason Meaning
CONSUMED The grant was used up (its single use, or its maxUsage). It authorizes nothing, and a re-pin never revives it.
REVOKED The grant was revoked. It authorizes nothing, and a re-pin never revives it.
SAME_VERSION The grant is already pinned to the requested version.
VERSION_NOT_IN_TENANT The requested version is not a version of a live Constraint Policy of your tenant. The answer is the same whether the version belongs to another tenant or exists nowhere.
OWNED_BY_USE_CASE The grant belongs to an Internal Crypto Use Case. The use case governs its grants' limits.
OWNED_BY_MARKETPLACE The grant belongs to the marketplace plan. A plan tier change re-pins it.

This is a distinct 409 from Concurrent Modification, which means a stale optimistic-lock version and succeeds on a retry after a re-read. A client branches on the type member and on reason, never on detail.

Common Causes

  • Re-pinning a single-use grant after its one use was taken, or a grant whose Exchange was revoked.
  • A console tab or script that re-pinned the grant once and sent the same request again.
  • Passing a version id copied from another tenant, or the id of a policy instead of one of its versions.
  • Re-pinning a grant listed under an Internal Crypto Use Case or under the marketplace plan.

Response Example

{
  "type": "https://docs.ankatech.co/errors/capability-grant-repin-refused",
  "title": "Capability Grant Re-pin Refused",
  "status": 409,
  "detail": "The Capability Grant is already pinned to the requested Constraint Policy version.",
  "instance": "/api/v3/admin/tenants/7c9e6679-7425-40de-944b-e07fc1f90ae7/capability-grants/22222222-2222-4222-8222-222222222222/policy-version",
  "timestamp": 1730000000,
  "extensions": {
    "reason": "SAME_VERSION",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json, following RFC 9457 Problem Details. The detail is fixed text for each reason and names no identifier.

How to Resolve

  1. Read extensions.reason.
  2. CONSUMED or REVOKED: the grant is finished. Create a new grant pinned to the version you want.
  3. SAME_VERSION: there is nothing to do; the grant already enforces that version.
  4. VERSION_NOT_IN_TENANT: list your policy's versions with listConstraintPolicyVersions and send one of their ids.
  5. OWNED_BY_USE_CASE or OWNED_BY_MARKETPLACE: change the limits through the owner, not through the grant.

Before re-pinning a grant that has been used, note how uses are counted. A grant keeps the uses already counted against it, and the new version's maxUsage applies to that count. Uses are counted only while the pinned version carries maxUsage or revokeOnUse, so uses made while no limit was pinned do not count toward a limit pinned later. See Constraint Policy — versions, re-pin and usage counting.

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