HEPH-IDEMP-400

Idempotency key missing or malformed

What the caller sees

This is the default detail sent in the problem+json response, verbatim:

The Idempotency-Key header is missing, empty, or not 1-255 printable ASCII characters without whitespace.

What to do as a developer

Guidance for the engineer who hit this code. It is non-normative: it is never sent on the wire and does not constrain an implementation. Wire behaviour is defined only by spec/heph-spec.md and the conformance vectors.

An endpoint that requires an Idempotency-Key received none, an empty one, or one that is not 1 to 255 printable ASCII characters (0x21-0x7E) with no whitespace. Send the header on every mutating request to such an endpoint, using a fresh opaque value such as a UUID per logical operation. Do not put personal data in the key; it is recorded as the idempotency.key telemetry attribute without redaction. Endpoints that do not require a key ignore a malformed one.

Defined in spec/heph-spec.md section 1. See all codes in the error index.