Skip to content

Tier Credential Self-Test Failed

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

When you see this

A candidate credential for an ANKA-managed tier failed the cross-credential round trip: an ephemeral key is wrapped under the credential currently in effect and unwrapped under the candidate, and only a candidate that reaches the same key-encryption key is accepted. This candidate did not. The same status is also returned when a tier's first credential is being established and the candidate does not complete its own round trip.

Common Causes

  • The candidate credential authenticates to a different key-encryption key than the one the tier's existing material was wrapped under.
  • The candidate credential is invalid, expired, or lacks the permissions the wrap and unwrap operations need.
  • The backend rejects the candidate, or a fault on the candidate's side prevents the unwrap from completing.

Response Example

{
  "type": "https://docs.ankatech.co/errors/tier-credential-self-test-failed",
  "title": "Tier Credential Self-Test Failed",
  "status": 422,
  "detail": "The candidate credential did not complete a wrap/unwrap round trip. The previous credential is unchanged and remains in effect.",
  "instance": "/api/v3/admin/platform/key-backend/tiers/ENTERPRISE/credential",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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

How to Resolve

  1. Confirm the candidate credential addresses the same key-encryption key the tier already uses — a credential that is individually valid but reaches a different key is refused here on purpose.
  2. Check the credential's permissions on the backend: it must be able to unwrap material wrapped under the tier's key.
  3. Re-submit with a corrected candidate. Nothing was swapped: the live credential is byte-identical, the transient candidate envelope is deleted, and no wrap occurred under the candidate's key.

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