Cryptographic Failure

URI: https://docs.ankatech.co/errors/crypto
HTTP Status: 500 Internal Server Error

When you see this

A cryptographic operation failed for a reason the platform could not attribute to your request. This is the server-fault type: it means the failure was not classified, not that it was caused by something you sent.

This is not a retryable condition

A 500 from this type is a server fault, not a transient one. Retrying the identical request will produce the identical result. If a condition really is transient, it is reported as a 503 with a Retry-After header, not as this type.

What changed

Client-caused conditions used to arrive here. Several API operations wrapped every failure inside their handler and re-reported it as this 500, so a malformed input, an unknown key, a refused rotation and a genuine internal fault were indistinguishable on the wire — and the Admin API relay then re-reported the 500 as a retryable 502.

Those operations no longer wrap. A condition that has an owning error type now reaches you as that type, with its own status:

Malformed or unparseable input reaches you as 400 (Invalid Input, Invalid PKCS#7).
An unknown key, or one that does not belong to your tenant, reaches you as 404 (Resource Not Found) — the two are deliberately indistinguishable.
A semantically invalid request reaches you as 422 — for example Unsupported PKCS#7 Format, Decryption Failed, Purpose Required, Rotation Purpose Violation or Key Operations Narrowing Forbidden.
A payload above the configured limit reaches you as 413 (Payload Too Large).
A key-protection backend that is unbound, unreachable or misconfigured reaches you as 409 or 503, not as this type.

Common Causes

What remains under this type is genuinely server-side:

A cryptographic provider or JCA/Bouncy Castle primitive failed unexpectedly during the operation.
A keystore entry could not be read or deserialized because of a storage-layer fault.
An internal invariant was violated while assembling or disassembling a JWE/JWS structure.

How to Resolve

Do not retry. The condition is not transient, and retrying a mutating operation is never safe.
Record the correlationId from the response body (and the X-Correlation-Id response header) — it is the only key that ties your request to the server-side log entry, which carries the diagnosable cause. The response body deliberately does not.
Report the correlationId, the endpoint and the approximate timestamp to your administrator or to AnkaSecure support.

Dispatch on the type URI, never on the wording of detail. See Error Reference for the full type registry.