Skip to content

Undecryptable PQC Transport Body

URI: https://docs.ankatech.co/errors/pqc-transport-undecryptable
HTTP Status: 400 Bad Request

When you see this

The request carried X-PQC-Transport: true under a session the service holds, and its body did not open under that session's key. Nothing of the request was processed: the body is refused before it reaches the operation. Core API, Auth API and Admin API answer it with the same type, title and detail.

The answer is the same whatever made the body undecryptable, and it names no decryption step: a client learns that the body did not open, never why (RFC 7516 §11.5). A server-side fault keeps its own 500, so this 400 always means the body as sent.

Common Causes

  • The body was changed in transit or by an intermediary after it was sealed.
  • The body was sealed under another session's key, for example a key kept from an earlier handshake while X-PQC-Session names a newer session.
  • The body is shorter than the AES-GCM envelope (12-byte IV plus 16-byte tag), for example a truncated write.
  • The client seals the body in another layout than [IV 12 bytes][ciphertext][tag 16 bytes] (NIST SP 800-38D).

Response Example

{
  "type": "https://docs.ankatech.co/errors/pqc-transport-undecryptable",
  "title": "Undecryptable PQC Transport Body",
  "status": 400,
  "detail": "The request body could not be decrypted under the PQC transport session.",
  "instance": "/api/v3/crypto/encrypt",
  "correlationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "timestamp": 1730000000,
  "extensions": {
    "code": "pqc.transport.undecryptable"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The correlationId and extensions.code members are Core API's; Admin API carries the correlation id as extensions.requestId, and Auth API carries no correlation member in the body.

How to Resolve

  1. Check that the client seals each request body under the key of the session X-PQC-Session names, with a fresh 12-byte IV, in the [IV][ciphertext][tag] layout.
  2. If an intermediary can rewrite request bodies, exempt the PQC transport path from it; the body is authenticated and any change is refused.
  3. Do not retry the same bytes: a body that did not open will not open on a second attempt. Seal the request again, or run a new handshake if the session key may be out of step.

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