Skip to content

Tenant In Maintenance

URI: https://docs.ankatech.co/errors/tenant-in-maintenance
HTTP Status: 503 Service Unavailable

When you see this

Your application asked for a cryptographic or key operation — encrypt, decrypt, sign, verify, generate, rotate, import or another key-lifecycle operation — while its tenant is temporarily unavailable for those operations. Nothing was executed: no ciphertext, signature or key exists as a result of the request, and no use of a key was counted.

The tenant is in a short maintenance window scheduled by its administrator or by the platform operator. The window ends on its own; the same request succeeds once it has.

The answer is given only to a caller that authenticated as a member of that tenant. A request without a valid token, or with a token of another tenant, receives the 401 or 403 it would receive at any other time, never this type, so the state of a tenant is never disclosed to anyone outside it.

Response Example

{
  "type": "https://docs.ankatech.co/errors/tenant-in-maintenance",
  "title": "Tenant in maintenance",
  "status": 503,
  "detail": "The tenant is temporarily unavailable for cryptographic operations. Retry later.",
  "instance": "/api/v3/crypto/encrypt",
  "correlationId": "4d1f8a2c-73b6-4e09-a5d1-6c2e9b0f7a34",
  "timestamp": 1793696400
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The response carries Retry-After: 300.

The body states the condition and nothing else: it names no reason, no backend, no key and no end time. Retry-After is the only timing hint, and it is a constant, not a prediction of when the window ends.

Where it is answered

Both services that operate on a tenant's keys return it, with the same body and the same Retry-After: 300:

  • The key service (the cryptographic API): every operation that requires the tenant's cryptographic or key-lifecycle capability, on the buffered and the streaming routes — encryption and decryption, signing and verification, the combined and conversion operations, re-encryption and re-signature, key generation, import, rotation, revocation and destruction.
  • The administration API (its key plane under /api/v3/admin/tenants/{tenantId}/keys): every key-lifecycle operation — create, import, rotate, suspend, reactivate, revoke, archive, remove, destroy, export and metadata changes, the material-version writes, a change of a key's rotation schedule — and the operations that consume a capability grant. Listing keys, reading a key's metadata, its material versions, its rotation schedule and what each lifecycle act would do to it stay available during the window.

The administration API carries its request id under extensions.requestId instead of a top-level correlationId, as every administration API problem does. Only MAINTENANCE is answered this way: every other state that does not admit the operation — SUSPENDED, CLOSED, a deleted tenant — keeps its 403. Sign-in, password reset, user email correction, administrator appointment and the tenant's administration screens remain available throughout the window.

How to Resolve

  1. Retry the same request after the Retry-After delay. The request was not executed, so a retry performs the operation exactly once.
  2. Treat the refusal as availability, not authorization: do not re-authenticate, rotate credentials or alert on a permission problem. The tenant's audit trail records the window itself, not each refused request.
  3. If it persists beyond the window your tenant administrator announced, ask the tenant administrator: the window's progress is shown in the console under the tenant's key protection settings.

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