Skip to content

Backend Self-Test Unavailable

URI: https://docs.ankatech.co/errors/backend-selftest-unavailable
HTTP Status: 503 Service Unavailable

When you see this

A deployment key-protection backend command — the activation (POST /api/v3/admin/platform/setup/backend/activate) or the credential write (PATCH /api/v3/admin/platform/setup/backend/credential) — contacted the backend for its wrap/unwrap round trip and got no usable answer in time, or an answer asking it to slow down. extensions.reason is UNREACHABLE, TIMED_OUT or THROTTLED (a request-rate limit: AWS KMS ThrottlingException, Google Cloud KMS RESOURCE_EXHAUSTED, an Azure HTTP 429). Nothing was learned about the configuration or the credential, so this is the one self-test failure a retry can clear. The credential in effect is unchanged and nothing was activated. The response carries a Retry-After header.

A backend that answered and refused is not this type: it is Backend Self-Test Failed (422, no Retry-After), which names what the backend answered. A round trip for which no client could be built at all is that same 422 with reason ROUTING_UNAVAILABLE: nothing was contacted and the fault is on the platform side, so it is not retryable and neither command answers 502 for it.

On a PKCS#11 token UNREACHABLE also covers a loaded module whose session could not be opened for a reason the classification does not type, and a C_Login that failed with a return code outside the declared PIN set, such as CKR_DEVICE_ERROR. A module library that cannot be loaded at all is not this type: it is the 422 with DESCRIPTOR_INVALID, because a retry cannot change it.

Response Example

{
  "type": "https://docs.ankatech.co/errors/backend-selftest-unavailable",
  "title": "Backend Self-Test Unavailable",
  "status": 503,
  "detail": "The deployment key-protection backend could not be reached in time to complete a wrap/unwrap round trip. Nothing was learned about the configuration or the credential; retry shortly. The credential in effect is unchanged and nothing was activated.",
  "instance": "/api/v3/admin/platform/setup/backend/activate",
  "timestamp": 1730000000,
  "extensions": {
    "reason": "UNREACHABLE",
    "requestId": "b41d9a3c-7e21-4f88-9c0d-5a2f7b18e604"
  }
}

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

How to Resolve

  1. Wait the Retry-After interval and repeat the command.
  2. If it recurs, check the path from the platform to the backend: DNS, firewall or security group, VPC endpoint, any declared endpoint — and on a PKCS#11 token the module path, the vendor library install and the appliance link. POST /api/v3/admin/platform/setup/backend/validate rehearses the coordinates without a credential.

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