Error code: idempotency_key_malformed

What triggers it

The idempotency key was not a valid format. An empty key, or one over 255 characters.

Example response

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_malformed",
    "message": "The idempotency key was not a valid format.",
    "param": "Idempotency-Key"
  }
}

How to fix it

Send a non-empty key up to 255 chars — a UUID is ideal.

This is deterministic; fix the cause before resending. See the error code catalogue for related codes.

In practice

In a well-built client, idempotency_key_malformed is handled by branching on error.code rather than on the human error.message, which may be reworded over time. The HTTP status (400) gives the broad invalid_request_error class; the code gives the specifics; and, on field errors, error.param pinpoints the input to fix.

This code is deterministic — retrying the identical request reproduces it — so keep it out of your retry path and instead map it to a clear, actionable message. See Map errors to user-facing messages and Read the error envelope for the pattern.