Skip to content

Conflict

URI: https://docs.ankatech.co/errors/conflict
HTTP Status: 409 Conflict

When you see this

The server understood your request but cannot complete it because it would conflict with the current state of the target resource.

Common Causes

  • Duplicate kid
    You tried to import or register a key under an ID that already exists in the keystore.

  • Algorithm or material mismatch
    You attempted to generate or import a key under an existing kid, but the requested algorithm or public-key material doesn’t match the stored entry.

  • Logically-deleted key recreation
    You tried to recreate a key whose ID was marked DELETED_LOGICAL; logically-deleted keys cannot be recreated under the same ID.

  • Invalid key lifecycle state
    You attempted an operation on a key that’s in the wrong state (for example, revoking a key that’s already revoked).

  • Disallowed operation
    You used a key for an operation it doesn’t support (e.g. encrypting with a signature-only key, signing with an encryption-only key).

Not this type: the federated just-in-time provisioning conflict

A federated login whose identity provider asserts an email address already owned by another account in the tenant is also a 409, but it does not carry this generic type. It carries its own type https://docs.ankatech.co/errors/federated-email-conflict, title Federated Email Already Owned, so that the authentication service can classify it on the type member alone and route it to the operator instead of reporting it as a platform defect.

Do not treat a 409 on the federated provisioning path as a duplicate-resource conflict, and do not branch on this generic type to detect it. The two are separated deliberately:

  • errors/conflict remains in service for every other caller and is unchanged.
  • errors/federated-email-conflict is raised only on the internal federated provisioning call, whose sole caller is the authentication service. On the browser surface it is projected as access_not_configured; on a non-navigation surface a programmatic caller receives 403 admission-denied. Both are deliberate — see Federated Login Errors.

Response Example

{
  "type": "https://docs.ankatech.co/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A key with kid 'my-mlkem-key' already exists in this tenant.",
  "instance": "/api/v3/admin/tenants/2f1c9d84-6b2e-4d3a-9f57-0a1b2c3d4e5f/keys",
  "timestamp": 1751500800,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json — the response follows RFC 7807 Problem Details. The example above is an Admin API body, where the correlation identity is extensions.requestId; the Core API and the PQC Handshake API instead emit a top-level correlationId. Read the member your service emits — see Error Index & Overview.

When the conflict is detected by an internal upstream service, how much of that rejection you receive depends on the operation. Most operations that can conflict — key creation, key rotation, keystore import and key import — author their own 409 sentence and discard the upstream body entirely; an operation that declares no 409 arm of its own relays the upstream's type, title, detail and status instead. In every case instance and extensions.requestId are those of the service you called, and detail is a single sentence, never a nested document. The per-operation table is in S2S Relay Envelope.

How to Resolve

  1. Inspect the response detail to see which conflict occurred.
  2. For duplicate or mismatched keys
    • Choose a new, unique kid, or
    • Use the same algorithm and public-key material as the existing entry.
  3. For logically-deleted keys
    • Select a different kid, or
    • Permanently remove the old entry before reusing the ID.
  4. For invalid lifecycle states
    • Check the key’s status via
      GET /api/key-management/keys/{kid} (see the Developer Hub Reference)
    • Only perform operations allowed in that state (see Key Lifecycle in the API Reference).
  5. For disallowed operations
    • Ensure the key’s type and algorithm support the operation you’re requesting (encrypt, decrypt, sign, verify).

For full details on key-management rules and operations, see the Developer Hub Reference.