Tier Bind Self-Test Failed

URI: https://docs.ankatech.co/errors/tier-bind-self-test-failed
HTTP Status: 422 Unprocessable Entity

When you see this

The bind verb wraps and unwraps an ephemeral, non-tenant key against the tier's own declared key-protection backend, and the round trip failed for a reason waiting will not change — extensions.reason names which: the tier's configuration cannot produce a client, or the backend answered and refused (the credential, the operation, a missing key, a round-trip mismatch). An unchanged configuration will not start working on its own. A backend that was contacted and gave no answer in time is not this type: it is Tier Bind Self-Test Unavailable (503, with Retry-After); one no client could be routed to is Upstream Service Unavailable (502). The same classification decides the BYOK bind and the deployment activation. The tier was not bound and stays in DECLARED_PENDING_BIND, so binding again after correcting the configuration needs no other verb.

Common Causes

• A coordinate in the tier's declared backend configuration is wrong — endpoint, region, key identifier, vault or token label.
• The tier's credential is absent, or the backend rejects it.
• The platform could not build a client from the tier's declaration at all — a credential that will not unseal, a provider family that does not match the declared token. Nothing was contacted, and this is a platform-side configuration fault rather than an upstream one, which is why it is this 422 and never a 502.
• A host-side provisioning step the tier's activation hint names has not been completed yet.
• The platform could not build a client for the tier's backend at all (ROUTING_UNAVAILABLE): the detail then says nothing was contacted and no round trip ran, and the fault is in the tier's recorded credential or coordinates, not on the backend.
• The backend answered that the declared key does not exist — every Cloud KMS family reports it from its own not-found code, and the connection test names it KEY_ABSENT. It is corrected in the tier's key identifier, not in the network path.
• The round trip passed, but the provider refused to set the automatic rotation of the tier's key. The body then also carries extensions.step = ROTATION_SCHEDULE, and the detail says whether the tier credential lacks the provider's rotation permissions or the key cannot rotate automatically at all (AWS KMS imported key material or a custom key store, which a grant does not change) (the list^*). A failure of the round trip itself carries no step member.

Response Example

{
  "type": "https://docs.ankatech.co/errors/tier-bind-self-test-failed",
  "title": "Tier Bind Self-Test Failed",
  "status": 422,
  "detail": "This tier's key-protection backend did not complete a wrap/unwrap round trip with its current configuration. The tier was not bound and is unchanged.",
  "instance": "/api/v3/admin/platform/key-backend/tiers/ENTERPRISE/bind",
  "timestamp": 1730000000,
  "extensions": {
    "reason": "AUTHENTICATION_REFUSED",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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

The rotation step refused:

{
  "type": "https://docs.ankatech.co/errors/tier-bind-self-test-failed",
  "title": "Tier Bind Self-Test Failed",
  "status": 422,
  "detail": "This tier's key-protection backend completed the wrap/unwrap round trip but refused to set the automatic rotation of the tier's key: the tier credential lacks the provider's rotation permissions. The tier was not bound and is unchanged.",
  "instance": "/api/v3/admin/platform/key-backend/tiers/PROFESSIONAL/bind",
  "timestamp": 1730000000,
  "extensions": {
    "reason": "REFUSED",
    "step": "ROTATION_SCHEDULE",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

How to Resolve

1. Re-read the tier's declared configuration and correct the coordinate that is wrong. The body names no vendor, endpoint, region or label by design — the underlying fault is in the server-side log, correlated by the request id.
2. Complete the host-side provisioning step the tier's activation hint names, if one is outstanding.
3. With extensions.step = ROTATION_SCHEDULE, grant the tier credential the provider's rotation permissions; the round trip already passed.
4. Bind again. The tier is still in DECLARED_PENDING_BIND, so no reset or re-declaration is required.

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