Skip to content

Backend Endpoint Requirement Not Satisfied

URI: https://docs.ankatech.co/errors/byok-endpoint-requirement
HTTP Status: 422 Unprocessable Entity

When you see this

The endpoint you submitted does not satisfy the declared backend's own requirement: either the backend requires a connection endpoint and none was supplied, or it accepts none and one was. The request was refused before anything was written and before anything was contacted — no declaration was recorded, no coordinates were stored, and no outbound connection was opened.

The body is syntactically valid. The backend token is one of the nine, and the endpoint, when present, is a well-formed HTTPS URL. What the platform refuses is the pair: this backend, with an endpoint, or this backend, without one.

The requirement is a property of the backend family, declared once beside the platform's backend vocabulary and read by one component:

Declared backend endpoint What it is
azure-kv, azure-kv-mhsm required the vault URL the key name is resolved inside
aws-kms optional an egress pin; when supplied it is the address the platform dials
gcp-kms, gcp-kms-hsm not accepted the resource path in keyId already names the location
softhsm, nshield, luna, cloudhsm not accepted the token is reached through the deployment's own PKCS#11 library

A backend that does not accept an endpoint is refused for supplying one rather than ignoring it. An accepted-and-discarded field is a contract the platform does not honour, and the discard used to be six tokens wide.

Common Causes

  • An Azure Key Vault or Managed HSM backend declared without its vault URL.
  • A vault URL left in the form after switching the declared backend to a Cloud KMS or PKCS#11 token that accepts none.
  • A Google Cloud KMS backend given an endpoint. The location is a segment of the resource path in keyId; there is no separate host to name.
  • A PKCS#11 backend given a host. The token is reached through the deployment's PKCS#11 library, not over a network address the caller supplies.

How to Resolve

  1. Read detail. It states which half of the requirement was violated — a required endpoint that is absent, or an endpoint supplied to a backend that accepts none.
  2. Read extensions.field, which is always endpoint.
  3. Supply the endpoint, or remove it, and resubmit. If the endpoint was right and the backend token was wrong, correct the token instead.

The refusal names the case; it never names the value. No endpoint, host, region, resource path, project, ARN, vault URL or credential fragment appears in detail, in the extensions, or in the server-side log line. Naming which half was violated discloses nothing the caller did not send, and withholding it would make a published contract undiagnosable.

The pre-commit check answers this the same way, without writing. The POST .../validate rehearsals below run the same requirement check the commit runs, from the same single reader — which is what makes a green rehearsal predictive of the commit rather than merely adjacent to it. Unlike a coordinate that fails its grammar (an HTTP 200 carrying a FAILED verdict), an unsatisfied endpoint requirement is a 422 on the rehearsal too: the question cannot be answered for a pair the platform will not admit.

Where it is raised

  • PUT /api/v3/admin/platform/setup/backend/configuration — the deployment plane's write
  • POST /api/v3/admin/platform/setup/backend/validate — the deployment plane's rehearsal
  • PUT /api/v3/admin/tenants/{tenantId}/key-backend/byok and its platform-plane twin — per-tenant BYOK
  • POST /api/v3/admin/tenants/{tenantId}/key-backend/byok/validate and its platform-plane twin — the per-tenant rehearsal
  • POST /api/v3/admin/platform/key-backend/tiers/{tier}/validate — the managed-tier rehearsal