Skip to content

BYOK Credential Self-Test Unavailable

URI: https://docs.ankatech.co/errors/byok-credential-self-test-unavailable
HTTP Status: 503 Service Unavailable

When you see this

A new access credential submitted to rotate a tenant's own key-protection backend (BYOK) could not be verified, because the tenant's key service could not be reached while the platform checked it. Nothing was judged about the credential itself, and nothing was stored: the credential in force stays in force. The response carries a Retry-After header, and a retry with the same credential is the expected next step once the key service answers again.

This is the transient counterpart of BYOK Credential Self-Test Failed, which is the answer when the key service was reached and the new credential did not pass.

Common Causes

  • The key service endpoint was unreachable from the platform: DNS, firewall, security group, private endpoint or proxy.
  • The key service did not answer within the verification time budget, for example under heavy load.
  • The key service answered by asking the platform to slow down — a request-rate or quota limit at the provider (reason THROTTLED). It clears on its own; nothing in the new credential is implicated.

The platform failing to route the check to a key-protection backend at all is not this type: nothing is contacted then, and the rotation answers 502 Upstream Unavailable naming the key-protection service by role.

Response Example

{
  "type": "https://docs.ankatech.co/errors/byok-credential-self-test-unavailable",
  "title": "BYOK Credential Self-Test Unavailable",
  "status": 503,
  "detail": "The key backend could not be reached to verify the new credential. The current credential remains in force.",
  "instance": "/api/v3/admin/tenants/7d1c9b40-52e8-4a36-9f07-c3b81e6d240a/key-backend/byok/credential",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "3f6d2a91-8b4e-4c07-9e15-a2d8c4b7f031"
  }
}

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

How to Resolve

  1. Run the tenant's connection test (POST /api/v3/admin/tenants/{tenantId}/key-backend/byok/test). It uses the credential in force, changes nothing, and names whether the key service is unreachable or timing out.
  2. Correct the network path or wait for the key service to recover, as the test's verdict indicates.
  3. Submit the same credential again. Nothing was changed by the refused attempt: the credential in force, the tenant's declaration and its last recorded credential check are exactly as they were.

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