Timestamping Cannot Be Required

URI: https://docs.ankatech.co/errors/tsa-cannot-be-required
HTTP Status: 422 Unprocessable Entity

When you see this

A configuration write was refused because, once applied, it would leave one or more tenants required to carry an RFC 3161 timestamp on every signature while their time-stamping connection cannot produce one. The refusal is raised before anything is persisted: the configuration in force is exactly the one you had before the request.

A tenant is in that state when its effective TSA usage mode is REQUIRED and its effective connection fails at least one of three conditions:

• the connection is enabled;
• its endpoint is a valid https URL with a host;
• the deployment holds at least one ACTIVE TSA trust anchor.

The effective connection is the tenant's own connection override when it has one, and otherwise the deployment connection, taken whole. Signing for such a tenant is refused with 503 tsa-unavailable on every request, so the platform refuses the configuration change instead of letting the tenant's signing traffic discover it.

A write is refused only for the harm it adds. It is refused when a tenant that could stamp before the write could not after it, or when the write leaves the deployment default itself required to stamp without a capable connection where it was not before. A write that removes a requirement, or leaves an existing problem as it was, is accepted.

Which writes can be refused

Seven operations are checked, on the platform plane and on the tenant plane.

PUT /api/v3/admin/platform/settings/TSA_ENDPOINT_URL is never refused for this reason: a blank value, the only one that fails the endpoint condition, is already rejected with 400 by the setting's validator.

Common Causes

• Setting the deployment usage mode to REQUIRED before the deployment connection is enabled, has an endpoint, and has a trust anchor.
• Opening the deployment mode from DISABLED to OPTIONAL while tenants still hold ON selections they saved while the mode was DISABLED. Those selections take effect the moment the mode opens.
• A tenant administrator turning timestamping on for a tenant whose connection cannot stamp.
• Turning off or removing a tenant's own connection, or resetting the deployment connection, while tenants that rely on it are required to stamp.
• Retiring the last ACTIVE trust anchor before its replacement has been uploaded.

Response Example

A platform write — the deployment usage mode set to REQUIRED over a deployment connection that is switched off:

{
  "type": "https://docs.ankatech.co/errors/tsa-cannot-be-required",
  "title": "Timestamping Cannot Be Required",
  "status": 422,
  "detail": "This change would require timestamping over a time-stamping connection that is not configured to stamp, for tenants of this deployment, for the deployment default, or for both. Timestamping can be required only over a connection that is enabled and has a valid https endpoint, while at least one trust anchor is ACTIVE. To proceed anyway, repeat the request with acknowledgeAffectedTenants set to the reported affectedTenantCount.",
  "instance": "/api/v3/admin/platform/deployment/policies/tsa-usage",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "affectedTenantCount": 3,
    "deploymentDefaultAffected": true
  }
}

A platform write whose only effect is on the deployment default — every live tenant has a capable connection of its own, so no tenant is counted:

{
  "type": "https://docs.ankatech.co/errors/tsa-cannot-be-required",
  "title": "Timestamping Cannot Be Required",
  "status": 422,
  "detail": "This change would require timestamping over a time-stamping connection that is not configured to stamp, for tenants of this deployment, for the deployment default, or for both. Timestamping can be required only over a connection that is enabled and has a valid https endpoint, while at least one trust anchor is ACTIVE. To proceed anyway, repeat the request with acknowledgeAffectedTenants set to the reported affectedTenantCount.",
  "instance": "/api/v3/admin/platform/deployment/policies/tsa-usage",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "3b1f4c8e-2d6a-4f0e-9b57-8a4c2e1d6f30",
    "affectedTenantCount": 0,
    "deploymentDefaultAffected": true
  }
}

A tenant write — a tenant administrator setting the tenant's own selection to REQUIRED:

{
  "type": "https://docs.ankatech.co/errors/tsa-cannot-be-required",
  "title": "Timestamping Cannot Be Required",
  "status": 422,
  "detail": "Timestamping cannot be required for this tenant at this time. Contact your platform administrator.",
  "instance": "/api/v3/admin/tenants/550e8400-e29b-41d4-a716-446655440000/policies/tsa-usage",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "3f2a9c1e-8b47-4d2e-9a61-0c5e7d8f1b24"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

The detail is a fixed server sentence. The wording above is illustrative: dispatch on type and read the extension members, never the detail.

The platform body carries two extension members, both always present, and nothing else derived from a tenant:

• extensions.affectedTenantCount — how many tenants would move from able to stamp to unable to stamp. Live tenants are counted, suspended tenants included; closed tenants and the platform tenant are not. The body never names a tenant, an endpoint, a connection's provenance or an anchor figure.
• extensions.deploymentDefaultAffected — true when the write would also leave the deployment default, the connection every tenant without its own inherits, required to stamp while it cannot. A refusal can carry affectedTenantCount: 0 only when this member is true.

The tenant body carries neither member. It is the same, byte for byte apart from instance, timestamp and extensions.requestId, whichever condition failed, whether or not the tenant has its own connection, and whoever calls — a platform administrator writing on the tenant endpoint receives the same body. A tenant administrator cannot read the connection or the anchors, so the refusal reveals only what every signer in the tenant already learns from the 503 tsa-unavailable on signing: that the tenant cannot currently stamp.

Proceeding anyway

A platform operator can decide to proceed: for example, to make signing fail closed during a move to a new authority rather than let signatures go out without a timestamp. The platform points accept an acknowledgement; the tenant point does not.

1. Repeat the same request with the query parameter acknowledgeAffectedTenants set to the affectedTenantCount of the refusal you received:

   PUT /api/v3/admin/platform/deployment/policies/tsa-usage?acknowledgeAffectedTenants=3
   

2. The value is compared by equality with the count the server computes while applying the write. If the state moved in between — a tenant was created, an override removed — the count differs and the write is refused again with the fresh count. Resend the new count only after reading what changed.

3. When the refusal carried affectedTenantCount: 0 and deploymentDefaultAffected: true, the acknowledgement is acknowledgeAffectedTenants=0. A 0 sent against a refusal that counted tenants is a mismatch and is refused again.
4. A negative value never equals a count. On a write that is refused it is refused again with the fresh count; it is never a 400.
5. When the write is not refused, the parameter is ignored, whatever its value — including a value left over from an earlier refusal whose state has since changed.

The parameter is accepted by these six operations:

• replaceDeploymentTsaUsagePolicy — PUT /api/v3/admin/platform/deployment/policies/tsa-usage
• replacePlatformTimestampingOverride — PUT /api/v3/admin/platform/tenants/{tenantId}/settings/timestamping/override
• deletePlatformTimestampingOverride — DELETE on the same path
• updateSetting — PUT /api/v3/admin/platform/settings/{key}
• deleteSetting — DELETE /api/v3/admin/platform/settings/{key}
• retirePlatformTrustAnchor — POST /api/v3/admin/platform/tsa/trust-anchors/{id}/retire

The tenant point has no acknowledgement, for any caller. replaceTenantTsaUsagePolicy declares no such parameter: one sent anyway binds to nothing and the write is refused exactly as before. A tenant administrator who acknowledged would be consenting to an outage they cannot repair; the platform administrator repairs the connection instead.

Acknowledging does not make the configuration capable. It applies a configuration under which the counted tenants' signing requests are refused with 503 tsa-unavailable until the connection and the trust anchors are put right. Nothing is signed without the timestamp their policy requires.

How to Resolve

1. For a platform refusal, make the effective connection capable before repeating the write: enable the connection, give it a valid https endpoint, and upload at least one trust anchor on the Trust Anchors tab so it is ACTIVE. Then repeat the write with no acknowledgement.
2. When opening the deployment mode to OPTIONAL is refused, the counted tenants hold saved ON selections. Either make their connections capable first, or set those selections to OFF.
3. When retiring a trust anchor is refused, upload its replacement first so both are ACTIVE, then retire the outgoing one.
4. For a tenant refusal, ask your platform administrator to configure the time-stamping connection that serves your tenant.
5. If proceeding is the intended outcome, see Proceeding anyway.

If a platform timestamping write is being applied at the same moment, this request waits for it; when the wait exceeds its bound the request is refused with 503 serialised-operation-timeout and nothing is changed. Retry it. Two tenant usage-selection writes never wait for each other, because that point holds the serialising lock in shared mode. The two policy resets hold it too, although neither can be refused, and each in the mode of its own plane: the deployment reset exclusively, the tenant reset in shared mode. Both declare the 503.

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