Skip to content

Exchange Not Editable

URI: https://docs.ankatech.co/errors/exchange-not-editable
HTTP Status: 422 Unprocessable Content

When you see this

You asked to change a Cryptographic Exchange, and the Exchange's state does not admit that change. Nothing was written: the Exchange, its grants and its version are unchanged. The cause travels as the reason extension member, beside exchangeStatus:

Operation Refused when extensions.reason
updateExchange (PATCH /api/v3/admin/exchanges/{id}) The Exchange is past READY. Only a DRAFT or READY Exchange is edited; once it is ACTIVE, SUSPENDED or terminal, its endpoints and context are frozen STATUS_NOT_EDITABLE
createExchangeGrant, revokeExchangeGrant The Exchange is terminal (REVOKED, EXPIRED, CONSUMED). Its grants ended with it, and it accepts no grant change STATUS_NOT_EDITABLE
revokeExchangeGrant The grant is the last live grant of an ACTIVE or SUSPENDED Exchange, which keeps at least one LAST_LIVE_GRANT
updateExchange The request moves the Exchange to another Exchange Context while it owns live grants. Its grants authorize in its current context, so they are revoked before the Exchange moves CONTEXT_FIXED_WHILE_GRANTS_EXIST
createExchangeGrant The Exchange's context changed while the grant was being added. Re-read the Exchange and retry CONTEXT_FIXED_WHILE_GRANTS_EXIST

A client branches on reason, never on detail, which is prose.

Grants can be added to and removed from any non-terminal Exchange, ACTIVE included; only the endpoints and the context are frozen once the Exchange is in force.

The observed status travels as the exchangeStatus extension member. The activation refusal exchange-not-activatable publishes the same member for the same purpose.

This is not Invalid State Transition. That type answers a lifecycle change the current state does not permit — suspend, resume, revoke, validate or discard — and its remedy is to pick a transition that is valid from the current state. An edit requests no lifecycle change at all, so that remedy does not apply.

Common Causes

  • Editing an Exchange's origin, destination or context after activating it.
  • A console tab or script that read the Exchange while it was READY and saved after someone else activated it.
  • Removing the only grant of an active Exchange to replace it, instead of adding the replacement first.
  • Adding a grant to a revoked, expired or consumed Exchange to reuse it.

Response Example

{
  "type": "https://docs.ankatech.co/errors/exchange-not-editable",
  "title": "Exchange Not Editable",
  "status": 422,
  "detail": "This is the last live Capability Grant of a ACTIVE Exchange, which keeps at least one. Revoke the Exchange to end it, or add another grant first.",
  "instance": "/api/v3/admin/exchanges/7d2f4a10-9c31-4b8e-a5d6-2f11c0b47e93/grants/22222222-2222-4222-8222-222222222222",
  "timestamp": 1730000000,
  "extensions": {
    "reason": "LAST_LIVE_GRANT",
    "exchangeStatus": "ACTIVE",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json, following RFC 9457 Problem Details. Nothing you submitted in the body is echoed back.

How to Resolve

  1. Read extensions.reason and extensions.exchangeStatus.
  2. To change the endpoints or the context of an Exchange in use, clone it with cloneExchange (POST /api/v3/admin/exchanges/{id}/clone). The clone is a new DRAFT that can be edited, given its grants, validated and activated. Revoke the original with revokeExchange when it must stop authorizing.
  3. To move a DRAFT or READY Exchange to another context, revoke its grants with revokeExchangeGrant, change the context, then add the grants again.
  4. To replace the last grant of an active Exchange, add the new grant first, then remove the old one. A new grant that overlaps the old one for the same actor is refused with Capability Grant Overlap. When only the limits must change, re-pin the existing grant to another Constraint Policy version with replaceCapabilityGrantPolicyVersion instead; otherwise revoke the Exchange and compose a new one.
  5. A terminal Exchange cannot change. Clone it.

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